From 9a90bd69c51120cd037fab32dff200d1fea745ca Mon Sep 17 00:00:00 2001
From: lawrencecchen <54008264+lawrencecchen@users.noreply.github.com>
Date: Mon, 24 Aug 2026 23:37:29 -0700
Subject: [PATCH 1/3] feat(backend): add the cmux-tui session-provider adapter

cmux-tui is the headless Rust terminal multiplexer from manaflow-ai/cmux
(cmux-tui/), a different product from the macOS GUI app bin/backends/cmux.sh
drives. One dedicated headless session per firstmate home (fm-<hometag>,
server start --session --headless --state), one workspace per task with one
terminal tab, target string <workspace_id>:<terminal_id>.

Live-verified against 0.1.0: durable ids across server restarts (ids are
recovery authority; names are display labels behind the exactly-one
duplicate guard), write --text never auto-submits, screen read works on
fresh terminals and carries the cursor (composer capability cursor=1 into
the shared classifier), last-workspace close works, process show cwd plus
child-pid lsof//proc fallback replaces the screen-scraped pwd probe, and
mutations ride per-attempt correlation-key nonces retried once on typed
retryable/indeterminate errors.

Registry wiring: known/spawn lists, required tools (cmux-tui jq treehouse),
runtime detection from CMUX_TUI_SOCKET (legacy CMUX_MUX_SOCKET) after
tmux/herdr and before the GUI cmux markers, endpoint validation, dispatch
arms (capture, keys, submit, kill, composer, busy via the native hook-fed
agent record, target-exists), fm-spawn create/steer/meta arms with the
--secondmate refusal, control-lib key support, and the bootstrap install
hint.
---
 bin/backends/cmux-tui.sh | 611 +++++++++++++++++++++++++++++++++++++++
 bin/fm-backend.sh        |  72 ++++-
 bin/fm-bootstrap.sh      |   1 +
 bin/fm-control-lib.sh    |   2 +-
 bin/fm-spawn.sh          |  27 +-
 5 files changed, 709 insertions(+), 4 deletions(-)
 create mode 100644 bin/backends/cmux-tui.sh

diff --git a/bin/backends/cmux-tui.sh b/bin/backends/cmux-tui.sh
new file mode 100644
index 00000000000..b382a84b91f
--- /dev/null
+++ b/bin/backends/cmux-tui.sh
@@ -0,0 +1,611 @@
+#!/usr/bin/env bash
+# bin/backends/cmux-tui.sh - the cmux-tui session-provider adapter
+# (EXPERIMENTAL). cmux-tui is the Rust terminal multiplexer in
+# manaflow-ai/cmux `cmux-tui/`, NOT the macOS GUI app that
+# bin/backends/cmux.sh drives; the two adapters are independent.
+#
+# Function prefix: fm_backend_cmuxtui_* (the backend NAME is "cmux-tui",
+# but shell function names cannot carry the hyphen portably, so the
+# dispatcher's cmux-tui case arms call the cmuxtui-prefixed family).
+#
+# cmux-tui is a session provider ONLY, exactly like tmux/herdr/zellij: the
+# worktree provider stays treehouse. Sourced only through bin/fm-backend.sh's
+# fm_backend_source in normal operation; the unit tests source it directly.
+#
+# Container shape: cmux-tui HAS a real session layer (unlike the GUI app).
+# ONE dedicated headless cmux-tui session per firstmate home, named
+# "fm-<hometag>" (bin/fm-backend-hometag-lib.sh), started with
+# `server start --session <name> --headless --state <dir>` against an
+# adapter-owned state dir. ONE workspace per task with exactly one terminal
+# tab inside it. Because the session itself is home-scoped, workspace names
+# are the PLAIN caller-facing "fm-<id>" labels - no title tag is needed for
+# cross-home isolation (the tag lives in the session name instead).
+#
+# Target string shape: "<workspace_id>:<terminal_id>" - typed opaque ids
+# ("ws_<hex>", "term_<hex>") with no embedded colon, so splitting on the
+# FIRST colon is trivially correct (herdr/zellij/cmux convention).
+#
+# Empirical findings (real cmux-tui 0.1.0 @ 4471965b12, macOS aarch64,
+# 2026-08-24; docs/verification/runtime-backends.md "cmux-tui" has the
+# evidence log) that shaped this adapter:
+#
+#   1. IDs are DURABLE across server restarts: after `server stop` +
+#      `server start --state <same dir>`, `workspace list` and
+#      `terminal <id> show` return the SAME ws_/term_ ids (verified live).
+#      IDs are therefore the recovery authority; workspace names are display
+#      labels only, adopted only through the standard exactly-one duplicate
+#      guard when a recorded id has genuinely disappeared.
+#   2. `terminal <id> write --text` does NOT auto-submit; `keys enter` is a
+#      separate call - the fleet-wide literal-then-Enter contract, verified.
+#   3. `screen read` works on a genuinely FRESH terminal (no GUI-cmux
+#      fresh-surface internal_error) and returns cursor_row/cursor_col plus
+#      cursor_visible, giving this adapter a cursor primitive the GUI app
+#      lacks (composer capability cursor=1).
+#   4. Closing the LAST workspace of a session works; the session server
+#      keeps running with an empty tree (no GUI-cmux last-in-window sibling
+#      dance, no zellij ghost tab).
+#   5. `process show --json` reports the top-level shell's cwd as a
+#      file://<host>/path URL (strip scheme+host) and its child pids. The
+#      structured cwd follows a `cd` typed into an OSC7-integrated shell but
+#      stays FROZEN when a foreground subshell without shell integration
+#      (exactly what `treehouse get` opens) does its own cd - verified with
+#      `env -i bash --norc`. The live answer for that case is the child
+#      pid's OS-level cwd: `lsof -a -p <pid> -d cwd -Fn` on macOS,
+#      /proc/<pid>/cwd on Linux. No screen-scraped pwd-marker probe needed.
+#   6. NO workspace-name uniqueness enforcement (two workspaces created with
+#      one name, verified). The duplicate refusal below is ours, mirroring
+#      every other adapter.
+#   7. Mutations accept --correlation-key: replaying the same key returns
+#      the ORIGINAL result with replayed:true - even after the created
+#      workspace was closed (verified), so keys must be per-attempt nonces
+#      used only to retry the SAME indeterminate attempt, never derived from
+#      stable labels.
+#   8. Typed JSON errors ({code, message, retryable, details}), e.g.
+#      selector.not_found, validation.invalid, mutation.indeterminate. The
+#      mutate wrapper retries once on a retryable/indeterminate error with
+#      the SAME correlation key (act-then-handle, not check-then-act).
+#   9. Native per-terminal agent state exists: `agent list --json` rows
+#      carry state working|blocked|idle|done|unknown (hook-fed via
+#      `agent report`/`agent hook install`), the same vocabulary as herdr's
+#      agent_status, mapped the same way for fm_backend_busy_state.
+#  10. The per-uid socket dir is 0700 and same-user; there is no
+#      socketControlMode matrix and no password handshake (the GUI app's
+#      whole auth section does not exist here).
+#
+# Config isolation is load-bearing: the operator's own ~/.config/cmux/
+# cmux-tui.json may configure a machine provider that refuses
+# --session/--headless startup, so EVERY invocation exports CMUX_TUI_CONFIG
+# pointing at an adapter-owned config file (fm_backend_cmuxtui_config).
+#
+# Requires: cmux-tui (CLI; override with FM_CMUXTUI_BIN), jq (JSON parsing).
+# Bootstrap detects these through fm_backend_required_tools only when
+# cmux-tui is the resolved backend; this adapter also gates them again
+# before spawning.
+
+# FM_HOME fallback: every real caller already sets FM_HOME as a global before
+# sourcing fm-backend.sh (which sources this file); this exists only so this
+# file's own unit tests, which source it directly, resolve sanely. Mirrors
+# bin/backends/zellij.sh's identical fallback.
+FM_BACKEND_CMUXTUI_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+FM_ROOT="${FM_ROOT_OVERRIDE:-${FM_ROOT:-$FM_BACKEND_CMUXTUI_ROOT}}"
+FM_HOME="${FM_HOME:-${FM_ROOT_OVERRIDE:-$FM_ROOT}}"
+
+# shellcheck source=bin/fm-backend-hometag-lib.sh
+. "$FM_BACKEND_CMUXTUI_ROOT/bin/fm-backend-hometag-lib.sh"
+
+# Shared composer classification (the fleet-wide shape catalogue and verdict
+# owner; this adapter contributes only capture and capability facts).
+# shellcheck source=bin/fm-composer-lib.sh
+. "$FM_BACKEND_CMUXTUI_ROOT/bin/fm-composer-lib.sh"
+
+# Verified minimum: the version the live pass ran against
+# (docs/verification/runtime-backends.md "cmux-tui").
+FM_BACKEND_CMUXTUI_MIN_MAJOR=0
+FM_BACKEND_CMUXTUI_MIN_MINOR=1
+
+# fm_backend_cmuxtui_bin: resolve the cmux-tui CLI binary. FM_CMUXTUI_BIN
+# overrides (test isolation and non-PATH installs); otherwise PATH.
+fm_backend_cmuxtui_bin() {
+  if [ -n "${FM_CMUXTUI_BIN:-}" ]; then
+    printf '%s' "$FM_CMUXTUI_BIN"
+    return 0
+  fi
+  command -v cmux-tui 2>/dev/null && return 0
+  return 1
+}
+
+fm_backend_cmuxtui_tool_check() {
+  fm_backend_cmuxtui_bin >/dev/null 2>&1 || { echo "error: backend=cmux-tui selected but the 'cmux-tui' CLI was not found on PATH (set FM_CMUXTUI_BIN or install it from https://github.com/manaflow-ai/cmux)" >&2; return 1; }
+  command -v jq >/dev/null 2>&1 || { echo "error: backend=cmux-tui selected but 'jq' is not installed (required to parse cmux-tui's JSON output)" >&2; return 1; }
+  return 0
+}
+
+# fm_backend_cmuxtui_session: the home-scoped session name. One dedicated
+# headless session per firstmate home ("fm-<hometag>"), so crews are isolated
+# per home AND from the operator's own interactive cmux-tui sessions
+# (including the default "main" session, which this adapter never touches).
+# FM_CMUXTUI_SESSION overrides for test isolation, mirroring FM_ZELLIJ_SESSION.
+fm_backend_cmuxtui_session() {
+  if [ -n "${FM_CMUXTUI_SESSION:-}" ]; then
+    printf '%s' "$FM_CMUXTUI_SESSION"
+    return 0
+  fi
+  printf 'fm-%s' "$(fm_backend_hometag)"
+}
+
+# fm_backend_cmuxtui_state_dir: the adapter-owned durable state dir handed to
+# `server start --state`. Durable ids (finding #1) live here, so it must be a
+# per-home stable path: <state>/cmux-tui under the home's own state root.
+# FM_CMUXTUI_STATE overrides for test isolation.
+fm_backend_cmuxtui_state_dir() {
+  if [ -n "${FM_CMUXTUI_STATE:-}" ]; then
+    printf '%s' "$FM_CMUXTUI_STATE"
+    return 0
+  fi
+  printf '%s/cmux-tui' "${FM_STATE_OVERRIDE:-$FM_HOME/state}"
+}
+
+# fm_backend_cmuxtui_config: the adapter-owned CMUX_TUI_CONFIG file, created
+# as an empty JSON object on first use. Never the operator's own
+# ~/.config/cmux/cmux-tui.json: a machine_provider configured there makes
+# --session/--headless startup fail outright (see file header).
+# FM_CMUXTUI_CONFIG overrides for test isolation.
+fm_backend_cmuxtui_config() {
+  local cfg dir
+  cfg="${FM_CMUXTUI_CONFIG:-$(fm_backend_cmuxtui_state_dir)/cmux-tui.json}"
+  if [ ! -f "$cfg" ]; then
+    dir=$(dirname "$cfg")
+    mkdir -p "$dir" 2>/dev/null || true
+    printf '{}\n' > "$cfg" 2>/dev/null || true
+  fi
+  printf '%s' "$cfg"
+}
+
+# fm_backend_cmuxtui_cli: run `cmux-tui --session <home-session> <args...>`
+# with the adapter-owned config exported. The global --session flag routes
+# every scope/action through the home's dedicated session socket, so no call
+# can ever reach the operator's default "main" session.
+fm_backend_cmuxtui_cli() {  # <cmux-tui-scope-action-and-args...>
+  local bin
+  bin=$(fm_backend_cmuxtui_bin) || return 1
+  CMUX_TUI_CONFIG="$(fm_backend_cmuxtui_config)" \
+    "$bin" --session "$(fm_backend_cmuxtui_session)" "$@"
+}
+
+# fm_backend_cmuxtui_version_check: refuse loudly on a missing/incompatible
+# cmux-tui client. `cmux-tui --version` needs no socket (verified: prints
+# "cmux <semver> (<sha>; ghostty <sha>)" with no server running).
+fm_backend_cmuxtui_version_check() {
+  fm_backend_cmuxtui_tool_check || return 1
+  local bin raw ver major rest minor
+  bin=$(fm_backend_cmuxtui_bin) || return 1
+  raw=$("$bin" --version 2>/dev/null) || { echo "error: 'cmux-tui --version' failed; is cmux-tui installed correctly?" >&2; return 1; }
+  ver=$(printf '%s' "$raw" | awk '{print $2}')
+  case "$ver" in
+    ''|*[!0-9.]*)
+      echo "error: could not parse a cmux-tui version from '$raw'; refusing to use an unverified cmux-tui build" >&2
+      return 1
+      ;;
+  esac
+  major=${ver%%.*}
+  rest=${ver#*.}
+  minor=${rest%%.*}
+  case "$major" in ''|*[!0-9]*) major=0 ;; esac
+  case "$minor" in ''|*[!0-9]*) minor=0 ;; esac
+  if [ "$major" -lt "$FM_BACKEND_CMUXTUI_MIN_MAJOR" ] || { [ "$major" -eq "$FM_BACKEND_CMUXTUI_MIN_MAJOR" ] && [ "$minor" -lt "$FM_BACKEND_CMUXTUI_MIN_MINOR" ]; }; then
+    echo "error: cmux-tui $ver is older than the verified minimum $FM_BACKEND_CMUXTUI_MIN_MAJOR.$FM_BACKEND_CMUXTUI_MIN_MINOR; update cmux-tui before using backend=cmux-tui" >&2
+    return 1
+  fi
+  return 0
+}
+
+# fm_backend_cmuxtui_server_running: passive, READ-ONLY liveness check for the
+# home's session server. `server status --session <name>` exits 0 only when
+# that named session's socket answers; it never starts anything.
+fm_backend_cmuxtui_server_running() {
+  local bin
+  bin=$(fm_backend_cmuxtui_bin) || return 1
+  CMUX_TUI_CONFIG="$(fm_backend_cmuxtui_config)" \
+    "$bin" server status --session "$(fm_backend_cmuxtui_session)" >/dev/null 2>&1
+}
+
+# fm_backend_cmuxtui_server_ensure: start the home's dedicated headless
+# session if it is not already running - mirrors tmux's
+# `has-session || new-session -d` and zellij's server_ensure. `server start`
+# runs foreground, so it is daemonized explicitly (nohup, detached, output to
+# a log inside the adapter state dir) and readiness is polled via
+# `server status`.
+fm_backend_cmuxtui_server_ensure() {
+  fm_backend_cmuxtui_server_running && return 0
+  local bin state session log i
+  bin=$(fm_backend_cmuxtui_bin) || return 1
+  state=$(fm_backend_cmuxtui_state_dir)
+  session=$(fm_backend_cmuxtui_session)
+  mkdir -p "$state" || { echo "error: cannot create cmux-tui state dir $state" >&2; return 1; }
+  log="$state/server.log"
+  ( CMUX_TUI_CONFIG="$(fm_backend_cmuxtui_config)" \
+      nohup "$bin" server start --session "$session" --headless --state "$state" \
+      </dev/null >>"$log" 2>&1 & ) || return 1
+  for i in $(seq 1 40); do
+    fm_backend_cmuxtui_server_running && return 0
+    sleep 0.25
+  done
+  echo "error: cmux-tui session '$session' did not come up within 10s (see $log)" >&2
+  return 1
+}
+
+# fm_backend_cmuxtui_container_ensure: the full spawn-time container-ensure
+# sequence (version gate, headless session). Echoes the session name,
+# mirroring zellij's container_ensure.
+fm_backend_cmuxtui_container_ensure() {
+  local session
+  fm_backend_cmuxtui_version_check || return 1
+  fm_backend_cmuxtui_server_ensure || return 1
+  session=$(fm_backend_cmuxtui_session)
+  printf '%s' "$session"
+}
+
+# fm_backend_cmuxtui_mutate: run one mutating CLI action with a fresh
+# per-attempt --correlation-key nonce, retrying ONCE with the SAME key when
+# the typed error says the attempt was retryable or indeterminate
+# (mutation.indeterminate) - act-then-handle-typed-error, never a pre-check.
+# The key is a nonce, never label-derived: a replayed key returns the
+# ORIGINAL attempt's result even after that workspace was closed (verified,
+# finding #7), so a stable key would resurrect stale ids on a later task
+# reusing the same label. Echoes the (successful or failed) JSON response.
+fm_backend_cmuxtui_mutate() {  # <scope-action-and-args...>
+  local key out rc
+  key="fm-$$-$(date +%s)-$RANDOM$RANDOM"
+  out=$(fm_backend_cmuxtui_cli "$@" --correlation-key "$key" --json 2>&1)
+  rc=$?
+  if [ "$rc" -ne 0 ] && printf '%s' "$out" | jq -e '(.retryable == true) or (.code == "mutation.indeterminate")' >/dev/null 2>&1; then
+    out=$(fm_backend_cmuxtui_cli "$@" --correlation-key "$key" --json 2>&1)
+    rc=$?
+  fi
+  printf '%s' "$out"
+  return "$rc"
+}
+
+# fm_backend_cmuxtui_workspace_id_for_label: the live workspace id whose name
+# equals <label>, adopted ONLY when exactly one live workspace carries it -
+# the standard duplicate guard (cmux-tui enforces no name uniqueness itself,
+# finding #6). Ambiguity prints nothing and fails.
+fm_backend_cmuxtui_workspace_id_for_label() {  # <label>
+  local label=$1 rows count
+  rows=$(fm_backend_cmuxtui_cli workspace list --json 2>/dev/null) || return 1
+  count=$(printf '%s' "$rows" | jq -r --arg want "$label" '[.[]? | select(.name == $want)] | length' 2>/dev/null)
+  [ "$count" = "1" ] || return 1
+  printf '%s' "$rows" | jq -r --arg want "$label" '.[]? | select(.name == $want) | .id' 2>/dev/null | head -1
+}
+
+# fm_backend_cmuxtui_terminal_for_workspace: the first terminal id inside
+# <workspace_id>, resolved through one `session current snapshot` read
+# (workspace -> screens.workspace_id -> layout tab_ids -> tabs.content_id
+# where content_kind == "terminal"; chain verified live).
+fm_backend_cmuxtui_terminal_for_workspace() {  # <workspace_id>
+  local wsid=$1 snap
+  snap=$(fm_backend_cmuxtui_cli session current snapshot --json 2>/dev/null) || return 1
+  printf '%s' "$snap" | jq -r --arg ws "$wsid" '
+    [.screens[]? | select(.workspace_id == $ws) | .layout | .. | .tab_ids? // empty | .[]] as $tabs
+    | [.tabs[]? | select((.id as $t | $tabs | index($t)) and .content_kind == "terminal") | .content_id]
+    | first // empty
+  ' 2>/dev/null
+}
+
+# fm_backend_cmuxtui_create_task: create the task's workspace (one terminal
+# tab) in the home session, refusing an existing live <label> (finding #6:
+# cmux-tui enforces no uniqueness itself; the TOCTOU between this check and
+# the create is inherent and documented). Echoes
+# "<workspace_id> <terminal_id>" on success.
+fm_backend_cmuxtui_create_task() {  # <label> <cwd>
+  local label=$1 cwd=$2 dup out wsid termid
+  dup=$(fm_backend_cmuxtui_cli workspace list --json 2>/dev/null \
+    | jq -r --arg want "$label" '.[]? | select(.name == $want) | .id' 2>/dev/null | head -1)
+  if [ -n "$dup" ]; then
+    echo "error: cmux-tui workspace '$label' already exists in session '$(fm_backend_cmuxtui_session)'" >&2
+    return 1
+  fi
+  out=$(fm_backend_cmuxtui_mutate workspace create --name "$label" --empty) || {
+    echo "error: cmux-tui workspace create failed for '$label': $out" >&2
+    return 1
+  }
+  wsid=$(printf '%s' "$out" | jq -r '.value.workspace_id // empty' 2>/dev/null)
+  [ -n "$wsid" ] || { echo "error: could not parse a cmux-tui workspace id for '$label' from: $out" >&2; return 1; }
+  out=$(fm_backend_cmuxtui_mutate tab create terminal --workspace "$wsid" --cwd "$cwd") || {
+    echo "error: cmux-tui tab create terminal failed for '$label' ($wsid): $out" >&2
+    fm_backend_cmuxtui_cli workspace "$wsid" close >/dev/null 2>&1 || true
+    return 1
+  }
+  termid=$(printf '%s' "$out" | jq -r '.value.terminal_id // empty' 2>/dev/null)
+  [ -n "$termid" ] || { echo "error: could not parse a cmux-tui terminal id for '$label' ($wsid) from: $out" >&2; return 1; }
+  printf '%s %s' "$wsid" "$termid"
+}
+
+# fm_backend_cmuxtui_parse_target: split "<workspace_id>:<terminal_id>" on the
+# FIRST colon (neither typed id contains a colon, so this is unambiguous).
+# Sets FM_BACKEND_CMUXTUI_WORKSPACE and FM_BACKEND_CMUXTUI_TERMINAL.
+fm_backend_cmuxtui_parse_target() {  # <target>
+  local target=$1
+  FM_BACKEND_CMUXTUI_WORKSPACE=${target%%:*}
+  FM_BACKEND_CMUXTUI_TERMINAL=${target#*:}
+  [ -n "$FM_BACKEND_CMUXTUI_WORKSPACE" ] && [ -n "$FM_BACKEND_CMUXTUI_TERMINAL" ] && [ "$FM_BACKEND_CMUXTUI_TERMINAL" != "$target" ]
+}
+
+fm_backend_cmuxtui_terminal_exists() {  # <terminal_id>
+  fm_backend_cmuxtui_cli terminal "$1" show --json >/dev/null 2>&1
+}
+
+fm_backend_cmuxtui_workspace_name_of_id() {  # <workspace_id>
+  fm_backend_cmuxtui_cli workspace "$1" show --json 2>/dev/null \
+    | jq -r '.name // empty' 2>/dev/null
+}
+
+# fm_backend_cmuxtui_target_ready: parse the target and verify it is live.
+# Durable ids are the recovery authority (finding #1): the recorded pair is
+# trusted while the terminal answers `terminal <id> show`. With an
+# expected-label, the workspace name is verified against that plain label,
+# and two narrow refresh paths run when a component has genuinely died:
+#   - workspace alive but its terminal gone (the shell exited, which closes
+#     the terminal id): re-resolve the workspace's current terminal.
+#   - workspace id gone entirely: adopt by name ONLY through the standard
+#     exactly-one duplicate guard (names are display labels, never blind
+#     recovery authority), then resolve that workspace's terminal.
+fm_backend_cmuxtui_target_ready() {  # <target> [expected-label]
+  local expected_label=${2:-} name wsid termid
+  fm_backend_cmuxtui_parse_target "$1" || return 1
+  if [ -n "$expected_label" ]; then
+    name=$(fm_backend_cmuxtui_workspace_name_of_id "$FM_BACKEND_CMUXTUI_WORKSPACE")
+    if [ "$name" = "$expected_label" ]; then
+      fm_backend_cmuxtui_terminal_exists "$FM_BACKEND_CMUXTUI_TERMINAL" && return 0
+      wsid=$FM_BACKEND_CMUXTUI_WORKSPACE
+    elif [ -n "$name" ]; then
+      return 1
+    else
+      wsid=$(fm_backend_cmuxtui_workspace_id_for_label "$expected_label")
+      [ -n "$wsid" ] || return 1
+    fi
+    termid=$(fm_backend_cmuxtui_terminal_for_workspace "$wsid")
+    [ -n "$termid" ] || return 1
+    FM_BACKEND_CMUXTUI_WORKSPACE=$wsid
+    FM_BACKEND_CMUXTUI_TERMINAL=$termid
+    return 0
+  fi
+  fm_backend_cmuxtui_terminal_exists "$FM_BACKEND_CMUXTUI_TERMINAL"
+}
+
+# fm_backend_cmuxtui_screen_json: one `screen read` on the CURRENT parsed
+# terminal (caller has already run parse_target/target_ready), echoing the
+# raw JSON ({text, cursor_row, cursor_col, cursor_visible, rows, cols}).
+fm_backend_cmuxtui_screen_json() {
+  fm_backend_cmuxtui_cli terminal "$FM_BACKEND_CMUXTUI_TERMINAL" screen read --json 2>/dev/null
+}
+
+# fm_backend_cmuxtui_history_text: the terminal's retained scrollback (rows
+# scrolled out above the viewport) as plain text, styled runs joined and
+# right-trimmed. Verified contiguous with the visible screen (the last
+# history row immediately precedes the screen's first row) with next=null
+# even at ~900 retained rows, so history+screen is a seamless tail.
+fm_backend_cmuxtui_history_text() {
+  fm_backend_cmuxtui_cli terminal "$FM_BACKEND_CMUXTUI_TERMINAL" history read --json 2>/dev/null \
+    | jq -r '.rows[]? | [.runs[]?.text] | join("")' 2>/dev/null \
+    | sed 's/[[:space:]]*$//'
+}
+
+# fm_backend_cmuxtui_capture: bounded plain-text capture. `screen read` is
+# clamped to the live viewport, so a request larger than the visible screen
+# also fetches the retained scrollback via history read and trims locally
+# (the fleet's "fetch generous, trim locally" posture).
+fm_backend_cmuxtui_capture() {  # <target> <lines> [expected-label]
+  fm_backend_cmuxtui_target_ready "$1" "${3:-}" || return 1
+  local lines=${2:-40} screen visible
+  case "$lines" in ''|*[!0-9]*) lines=40 ;; esac
+  screen=$(fm_backend_cmuxtui_screen_json) || return 1
+  visible=$(printf '%s' "$screen" | jq -r '.text // empty' 2>/dev/null) || return 1
+  if [ "$(printf '%s\n' "$visible" | wc -l | tr -d '[:space:]')" -lt "$lines" ]; then
+    { fm_backend_cmuxtui_history_text; printf '%s\n' "$visible"; } | tail -n "$lines"
+    return 0
+  fi
+  printf '%s' "$visible" | tail -n "$lines"
+}
+
+# fm_backend_cmuxtui_send_literal: send TEXT as literal, UNSUBMITTED input -
+# the caller sends Enter separately. Verified (finding #2): `write --text`
+# does NOT auto-submit, matching every other backend's contract exactly.
+fm_backend_cmuxtui_send_literal() {  # <target> <text> [expected-label]
+  fm_backend_cmuxtui_target_ready "$1" "${3:-}" || return 1
+  fm_backend_cmuxtui_cli terminal "$FM_BACKEND_CMUXTUI_TERMINAL" write --text "$2" >/dev/null 2>&1
+}
+
+# fm_backend_cmuxtui_normalize_key: map firstmate's key vocabulary onto
+# cmux-tui's verified lowercase `keys` chords. Verified accepted live: enter,
+# escape, ctrl+c, ctrl+d, ctrl+u, tab, up, down (an invalid chord returns the
+# typed validation.invalid error).
+fm_backend_cmuxtui_normalize_key() {  # <key>
+  case "$1" in
+    Enter|enter) printf 'enter' ;;
+    Escape|escape|Esc|esc) printf 'escape' ;;
+    C-c|c-c|ctrl+c|Ctrl+c|Ctrl+C|ctrl-c) printf 'ctrl+c' ;;
+    C-d|c-d|ctrl+d|Ctrl+d|Ctrl+D|ctrl-d) printf 'ctrl+d' ;;
+    # C-u clears a composer line. fm-send.sh's muse interrupt path needs it to
+    # drop the prompt muse restores into the composer after Escape.
+    C-u|c-u|ctrl+u|Ctrl+u|Ctrl+U|ctrl-u) printf 'ctrl+u' ;;
+    Tab) printf 'tab' ;;
+    Up|up) printf 'up' ;;
+    Down|down) printf 'down' ;;
+    *) printf '%s' "$1" ;;
+  esac
+}
+
+# fm_backend_cmuxtui_send_key: one named special key.
+fm_backend_cmuxtui_send_key() {  # <target> <key> [expected-label]
+  fm_backend_cmuxtui_target_ready "$1" "${3:-}" || return 1
+  local key
+  key=$(fm_backend_cmuxtui_normalize_key "$2")
+  fm_backend_cmuxtui_cli terminal "$FM_BACKEND_CMUXTUI_TERMINAL" keys "$key" >/dev/null 2>&1
+}
+
+# fm_backend_cmuxtui_send_text_line: send one line of TEXT then submit.
+# Mirrors bin/backends/cmux.sh's contract: a failed Enter clears the partial
+# input with Ctrl-C and returns 1; a failed cleanup returns 2 (unsafe input).
+fm_backend_cmuxtui_send_text_line() {  # <target> <text> [expected-label]
+  fm_backend_cmuxtui_send_literal "$1" "$2" "${3:-}" || return 1
+  fm_backend_cmuxtui_send_key "$1" Enter "${3:-}" && return 0
+  fm_backend_cmuxtui_send_key "$1" C-c "${3:-}" >/dev/null 2>&1 && return 1
+  return 2
+}
+
+# --- composer capture and capability primitives ------------------------------
+#
+# `screen read` returns the visible screen as plain text PLUS the live cursor
+# position (cursor_row/cursor_col/cursor_visible), so this adapter declares
+# cursor=1: the shared classifier anchors shape selection on the row the
+# cursor actually occupies (tmux's own anchoring), instead of guessing the
+# bottom-most shape. The capture is plain text (styled=0), so ghost text is
+# unreadable and a bare glyph row carrying trailing text still degrades to
+# `unknown` - the cursor primitive improves shape selection, not content
+# confidence. A hidden cursor (cursor_visible=false, e.g. mid-redraw) drops
+# the cursor fact for that read rather than anchoring on a stale row.
+
+# fm_backend_cmuxtui_composer_state: thin adapter - capture plus capability
+# facts in, shared verdict out (bin/fm-composer-lib.sh owns every shape).
+fm_backend_cmuxtui_composer_state() {  # <target> [expected-label] -> empty|pending|pending-unproven|unknown
+  local screen text cy visible rows caps verdict
+  fm_backend_cmuxtui_target_ready "$1" "${2:-}" || { printf 'unknown'; return 0; }
+  screen=$(fm_backend_cmuxtui_screen_json) || { printf 'unknown'; return 0; }
+  text=$(printf '%s' "$screen" | jq -r '.text // empty' 2>/dev/null)
+  [ -n "$text" ] || { printf 'unknown'; return 0; }
+  visible=$(printf '%s' "$screen" | jq -r '.cursor_visible' 2>/dev/null)
+  cy=$(printf '%s' "$screen" | jq -r '.cursor_row // empty' 2>/dev/null)
+  rows=$(printf '%s' "$screen" | jq -r '.rows // empty' 2>/dev/null)
+  case "$rows" in ''|*[!0-9]*) rows=$FM_COMPOSER_CAPTURE_LINES ;; esac
+  if [ "$visible" = true ] && [ -n "$cy" ]; then
+    caps=$(printf 'styled=0\ncursor=1\nidentity=0\nrows=%s' "$rows")
+    verdict=$(fm_composer_classify_screen "$caps" "$text" "$cy")
+  else
+    caps=$(printf 'styled=0\ncursor=0\nidentity=0\nrows=%s' "$rows")
+    verdict=$(fm_composer_classify_screen "$caps" "$text")
+  fi
+  [ "$verdict" != need-identity ] || verdict=unknown
+  printf '%s' "$verdict"
+}
+
+# fm_backend_cmuxtui_send_text_submit: type <text> into <target> once (raw,
+# unsubmitted, via send_literal), then drive the shared verify-and-retry-Enter
+# loop (bin/fm-composer-lib.sh: fm_composer_submit_retry_core) against the
+# shared composer verdict. Echoes empty|pending|unknown|send-failed, a subset
+# of the proof-carrying submit vocabulary; Enter alone is retried, text is
+# never retyped.
+fm_backend_cmuxtui_send_text_submit() {  # <target> <text> <retries> <enter-sleep> <settle> [expected-label]
+  local target=$1 text=$2 retries=$3 sleep_s=$4 settle=$5 expected_label=${6:-}
+  fm_backend_cmuxtui_parse_target "$target" || { printf 'unknown'; return 0; }
+  fm_backend_cmuxtui_send_literal "$target" "$text" "$expected_label" || { printf 'send-failed'; return 0; }
+  sleep "$settle"
+  fm_composer_submit_retry_core fm_backend_cmuxtui_send_key fm_backend_cmuxtui_composer_state \
+    "$target" "$retries" "$sleep_s" "$expected_label"
+}
+
+# fm_backend_cmuxtui_pid_cwd: one process's live OS-level cwd -
+# /proc/<pid>/cwd on Linux, `lsof -a -p <pid> -d cwd -Fn` on macOS. Empty on
+# any failure (a raced-away pid is normal here).
+fm_backend_cmuxtui_pid_cwd() {  # <pid>
+  local pid=$1 out
+  case "$pid" in ''|*[!0-9]*) return 1 ;; esac
+  if [ -e "/proc/$pid/cwd" ]; then
+    readlink "/proc/$pid/cwd" 2>/dev/null
+    return $?
+  fi
+  out=$(lsof -a -p "$pid" -d cwd -Fn 2>/dev/null | awk '/^n/ { print substr($0, 2); exit }')
+  [ -n "$out" ] || return 1
+  printf '%s' "$out"
+}
+
+# fm_backend_cmuxtui_current_path: the live foreground cwd, or empty on any
+# error (mirrors every adapter's tolerant contract for fm-spawn.sh's
+# worktree-discovery poll). Structured, never screen-scraped:
+# `process show --json` gives the top-level shell's cwd (a file://<host>/path
+# URL; strip scheme and host) plus its child pids. The structured cwd stays
+# FROZEN when an integration-free foreground subshell (the `treehouse get`
+# case, finding #5) does its own cd, so child pids are consulted FIRST,
+# newest first, through their OS-level cwd (fm_backend_cmuxtui_pid_cwd); the
+# top-level cwd field is the fallback for a childless plain shell.
+fm_backend_cmuxtui_current_path() {  # <target> [expected-label]
+  local target=$1 expected_label=${2:-} proc pid p raw
+  fm_backend_cmuxtui_target_ready "$target" "$expected_label" || return 0
+  proc=$(fm_backend_cmuxtui_cli terminal "$FM_BACKEND_CMUXTUI_TERMINAL" process show --json 2>/dev/null) || return 0
+  while IFS= read -r pid; do
+    [ -n "$pid" ] || continue
+    p=$(fm_backend_cmuxtui_pid_cwd "$pid") || continue
+    if [ -n "$p" ]; then
+      printf '%s' "$p"
+      return 0
+    fi
+  done < <(printf '%s' "$proc" | jq -r '.children // [] | reverse | .[]' 2>/dev/null)
+  raw=$(printf '%s' "$proc" | jq -r '.cwd // empty' 2>/dev/null)
+  [ -n "$raw" ] || return 0
+  printf '%s' "$raw" | sed -E 's|^file://[^/]*||'
+}
+
+# fm_backend_cmuxtui_busy_state: semantic busy state from cmux-tui's native
+# per-terminal agent record (`agent list --json`, hook-fed via
+# `agent report`/`agent hook install`; finding #9). The state vocabulary is
+# identical to herdr's agent_status and is mapped identically: working ->
+# busy; idle/done -> idle; blocked -> idle (stuck waiting on the human, which
+# the watcher should surface, not suppress as busy); no row or anything
+# else -> unknown, the caller's cue to fall back to pane-regex detection.
+# The newest row wins when a terminal carries more than one report.
+fm_backend_cmuxtui_busy_state() {  # <target>
+  local raw
+  fm_backend_cmuxtui_parse_target "$1" || { printf 'unknown'; return 0; }
+  raw=$(fm_backend_cmuxtui_cli agent list --json 2>/dev/null \
+    | jq -r --arg t "$FM_BACKEND_CMUXTUI_TERMINAL" '
+        [.[]? | select(.terminal_id == $t)]
+        | sort_by(.updated_at_ms | tonumber? // 0)
+        | last | .state // empty
+      ' 2>/dev/null)
+  case "$raw" in
+    working) printf 'busy' ;;
+    idle|done) printf 'idle' ;;
+    blocked) printf 'idle' ;;
+    *) printf 'unknown' ;;
+  esac
+}
+
+# fm_backend_cmuxtui_kill: close the task's whole workspace, best-effort
+# (mirrors every other backend's `|| true` contract). Closing the LAST
+# workspace of the session works natively (finding #4) - the session server
+# keeps running with an empty tree - so there is no GUI-cmux sibling dance
+# and no zellij ghost-tab sweep. With an expected label, stale ids are
+# refreshed through target_ready's guarded recovery first, so the close can
+# never hit a workspace id that now belongs to nothing or to a different
+# live task name.
+fm_backend_cmuxtui_kill() {  # <target> [unused] [expected-label]
+  local expected_label=${3:-}
+  if [ -n "$expected_label" ]; then
+    fm_backend_cmuxtui_target_ready "$1" "$expected_label" || return 0
+  else
+    fm_backend_cmuxtui_parse_target "$1" || return 0
+  fi
+  fm_backend_cmuxtui_cli workspace "$FM_BACKEND_CMUXTUI_WORKSPACE" close >/dev/null 2>&1 || true
+}
+
+# fm_backend_cmuxtui_list_live: recovery/orphan discovery. Lists every
+# workspace in the home's own session whose name carries the fm- task
+# prefix, resolving each workspace's terminal through ONE snapshot read.
+# The session is home-scoped, so no cross-home filtering is needed and the
+# printed label is the plain workspace name. One
+# "<workspace_id>:<terminal_id>\t<fm-id>" line per live task workspace.
+# Read-only: an unreachable session simply lists nothing.
+fm_backend_cmuxtui_list_live() {
+  local snap
+  snap=$(fm_backend_cmuxtui_cli session current snapshot --json 2>/dev/null) || return 0
+  printf '%s' "$snap" | jq -r '
+    . as $s
+    | ($s.workspaces // []) | .[]
+    | select((.name // "") | startswith("fm-"))
+    | . as $ws
+    | ([$s.screens[]? | select(.workspace_id == $ws.id) | .layout | .. | .tab_ids? // empty | .[]]) as $tabs
+    | ([$s.tabs[]? | select((.id as $t | $tabs | index($t)) and .content_kind == "terminal") | .content_id] | first // empty) as $term
+    | select($term != "")
+    | "\($ws.id):\($term)\t\($ws.name)"
+  ' 2>/dev/null
+}
diff --git a/bin/fm-backend.sh b/bin/fm-backend.sh
index 2882f4a6af2..37504db7458 100644
--- a/bin/fm-backend.sh
+++ b/bin/fm-backend.sh
@@ -65,9 +65,13 @@ FM_BACKEND_CONFIG_DIR="${FM_CONFIG_OVERRIDE:-$FM_HOME/config}"
 # spawn-capable; unlike tmux/herdr/zellij it is also the worktree provider.
 # cmux is EXPERIMENTAL and spawn-capable, session-provider-only like
 # herdr/zellij - verified against the real 0.64.17 binary (docs/cmux-backend.md).
+# cmux-tui is EXPERIMENTAL and spawn-capable, session-provider-only, and a
+# DIFFERENT product from cmux: the Rust terminal multiplexer, headless and
+# cross-platform, with a real session layer and durable ids - verified
+# against the real 0.1.0 binary (docs/cmux-tui-backend.md).
 # codex-app remains deliberately absent; see docs/codex-app-backend.md.
-FM_BACKEND_KNOWN="tmux herdr zellij orca cmux"
-FM_BACKEND_SPAWN="tmux herdr zellij orca cmux"
+FM_BACKEND_KNOWN="tmux herdr zellij orca cmux cmux-tui"
+FM_BACKEND_SPAWN="tmux herdr zellij orca cmux cmux-tui"
 
 # fm_backend_list_contains: whitespace-delimited membership without relying on
 # shell word splitting. fm-backend.sh is normally sourced by bash scripts, but
@@ -152,6 +156,28 @@ fm_backend_detect() {
     printf 'herdr'
     return 0
   fi
+  # cmux-tui injects CMUX_TUI_SOCKET (and the legacy CMUX_MUX_SOCKET alias)
+  # into every terminal it spawns, alongside CMUX_TUI_SESSION_ID and
+  # CMUX_TUI_TERMINAL_ID (verified live, cmux-tui 0.1.0). It is checked
+  # AFTER tmux/herdr (both can nest inside a cmux-tui terminal, and each
+  # sets its own marker in every nested process, so an inner multiplexer
+  # marker always means that multiplexer is the currently-executing layer)
+  # and BEFORE the cmux GUI markers: a cmux-tui session started inside a
+  # cmux GUI tab inherits the GUI's CMUX_WORKSPACE_ID into its terminals
+  # (verified live), so the inner cmux-tui marker must win over the outer
+  # GUI app's. CMUX_TUI_CONFIG is deliberately NOT a marker: it is a
+  # user-settable override this repo's own adapter exports on every CLI
+  # call, so its presence never reliably means "inside a cmux-tui terminal".
+  if [ -n "${CMUX_TUI_SOCKET:-}" ] || [ -n "${CMUX_MUX_SOCKET:-}" ]; then
+    FM_BACKEND_DETECTED=cmux-tui
+    if [ -n "${CMUX_TUI_SOCKET:-}" ]; then
+      FM_BACKEND_DETECT_SIGNAL=CMUX_TUI_SOCKET
+    else
+      FM_BACKEND_DETECT_SIGNAL=CMUX_MUX_SOCKET
+    fi
+    printf 'cmux-tui'
+    return 0
+  fi
   if [ -n "${CMUX_WORKSPACE_ID:-}" ]; then
     FM_BACKEND_DETECTED=cmux
     FM_BACKEND_DETECT_SIGNAL=CMUX_WORKSPACE_ID
@@ -262,6 +288,9 @@ fm_backend_name() {
     if [ "$detected" = herdr ]; then
       echo "NOTICE: auto-detected herdr runtime (HERDR_ENV=1) - spawning into the EXPERIMENTAL herdr backend. Set config/backend or pass --backend tmux to opt out." >&2
     fi
+    if [ "$detected" = cmux-tui ]; then
+      echo "NOTICE: auto-detected cmux-tui runtime ($FM_BACKEND_DETECT_SIGNAL) - spawning into the EXPERIMENTAL cmux-tui backend. Set config/backend or pass --backend tmux to opt out." >&2
+    fi
     if [ "$detected" = cmux ]; then
       case "$FM_BACKEND_DETECT_SIGNAL" in
         bundle-id) marker="FALLBACK signal __CFBundleIdentifier=$FM_BACKEND_CMUX_BUNDLE_ID; CMUX_WORKSPACE_ID absent, stripped by cmux's bundled claude wrapper" ;;
@@ -314,6 +343,7 @@ fm_backend_required_tools() {  # <backend>
     herdr)  printf '%s' 'herdr jq treehouse' ;;
     zellij) printf '%s' 'zellij jq treehouse' ;;
     cmux)   printf '%s' 'cmux jq treehouse' ;;
+    cmux-tui) printf '%s' 'cmux-tui jq treehouse' ;;
     orca)   printf '%s' 'orca' ;;
     *) return 1 ;;
   esac
@@ -328,6 +358,10 @@ fm_backend_required_tool_available() {  # <backend> <tool>
       fm_backend_source cmux >/dev/null 2>&1 || return 1
       fm_backend_cmux_bin >/dev/null 2>&1
       ;;
+    cmux-tui:cmux-tui)
+      fm_backend_source cmux-tui >/dev/null 2>&1 || return 1
+      fm_backend_cmuxtui_bin >/dev/null 2>&1
+      ;;
     *) command -v "$tool" >/dev/null 2>&1 ;;
   esac
 }
@@ -523,6 +557,23 @@ fm_backend_validate_task_endpoint() {  # <meta-file> <task-id>
         return 1
       fi
       ;;
+    cmux-tui)
+      [ "$binding" = "$id" ] || {
+        echo "REFUSED: legacy cmux-tui endpoint metadata for task $id lacks an exact task binding; preserving task state." >&2
+        return 1
+      }
+      recorded_session=$(fm_backend_meta_exact_value "$meta" cmuxtui_session) || recorded_session=
+      workspace=$(fm_backend_meta_exact_value "$meta" cmuxtui_workspace_id) || workspace=
+      terminal=$(fm_backend_meta_exact_value "$meta" cmuxtui_terminal_id) || terminal=
+      if [ -z "$recorded_session" ] || [ -z "$workspace" ] || [ -z "$terminal" ] \
+        || [ "$window" != "$workspace:$terminal" ] \
+        || ! fm_backend_endpoint_atom_valid "$recorded_session" \
+        || ! fm_backend_endpoint_atom_valid "$workspace" \
+        || ! fm_backend_endpoint_atom_valid "$terminal"; then
+        echo "REFUSED: cmux-tui endpoint metadata for task $id is malformed or inconsistent; preserving task state." >&2
+        return 1
+      fi
+      ;;
   esac
   # shellcheck disable=SC2034 # Output globals are consumed by sourcing callers.
   FM_BACKEND_VALIDATED_BACKEND=$backend
@@ -631,6 +682,13 @@ fm_backend_source() {  # <name>
         _FM_BACKEND_CMUX_SOURCED=1
       fi
       ;;
+    cmux-tui)
+      if [ -z "${_FM_BACKEND_CMUXTUI_SOURCED:-}" ]; then
+        # shellcheck source=/dev/null
+        . "$FM_BACKEND_LIB_DIR/backends/cmux-tui.sh" || return 1
+        _FM_BACKEND_CMUXTUI_SOURCED=1
+      fi
+      ;;
   esac
 }
 
@@ -702,6 +760,7 @@ fm_backend_capture() {  # <backend> <target> <lines> [expected-label]
     zellij) fm_backend_zellij_capture "$@" ;;
     orca) fm_backend_orca_capture "$@" ;;
     cmux) fm_backend_cmux_capture "$@" ;;
+    cmux-tui) fm_backend_cmuxtui_capture "$@" ;;
     *) echo "error: no capture implementation for backend '$backend'" >&2; return 1 ;;
   esac
 }
@@ -717,6 +776,7 @@ fm_backend_send_key() {  # <backend> <target> <key> [expected-label]
     zellij) fm_backend_zellij_send_key "$@" ;;
     orca) fm_backend_orca_send_key "$@" ;;
     cmux) fm_backend_cmux_send_key "$@" ;;
+    cmux-tui) fm_backend_cmuxtui_send_key "$@" ;;
     *) echo "error: no send-key implementation for backend '$backend'" >&2; return 1 ;;
   esac
 }
@@ -734,6 +794,7 @@ fm_backend_send_text_submit() {  # <backend> <target> <text> <retries> <enter-sl
     zellij) fm_backend_zellij_send_text_submit "$@" ;;
     orca) fm_backend_orca_send_text_submit "$@" ;;
     cmux) fm_backend_cmux_send_text_submit "$@" ;;
+    cmux-tui) fm_backend_cmuxtui_send_text_submit "$@" ;;
     *) echo "error: no send-text implementation for backend '$backend'" >&2; return 1 ;;
   esac
 }
@@ -752,6 +813,7 @@ fm_backend_kill() {  # <backend> <target>
     zellij) fm_backend_zellij_kill "$@" ;;
     orca) fm_backend_orca_kill "$@" ;;
     cmux) fm_backend_cmux_kill "$@" ;;
+    cmux-tui) fm_backend_cmuxtui_kill "$@" ;;
     *) echo "error: no kill implementation for backend '$backend'" >&2; return 1 ;;
   esac
 }
@@ -789,6 +851,7 @@ fm_backend_busy_state() {  # <backend> <target>
   fm_backend_source "$backend" || { printf 'unknown'; return 0; }
   case "$backend" in
     herdr) fm_backend_herdr_busy_state "$@" ;;
+    cmux-tui) fm_backend_cmuxtui_busy_state "$@" ;;
     *) printf 'unknown' ;;
   esac
 }
@@ -814,6 +877,7 @@ fm_backend_composer_state() {  # <backend> <target> [expected-label] -> empty|pe
     herdr) fm_backend_herdr_composer_state "$@" ;;
     orca) fm_backend_orca_composer_state "$@" ;;
     cmux) fm_backend_cmux_composer_state "$@" ;;
+    cmux-tui) fm_backend_cmuxtui_composer_state "$@" ;;
     zellij) fm_backend_zellij_composer_state "$@" ;;
     *) printf 'unknown' ;;
   esac
@@ -864,6 +928,10 @@ fm_backend_target_exists() {  # <backend> <target> [expected-label]
       fm_backend_source cmux || return 1
       fm_backend_cmux_target_ready "$target" "$expected_label"
       ;;
+    cmux-tui)
+      fm_backend_source cmux-tui || return 1
+      fm_backend_cmuxtui_target_ready "$target" "$expected_label"
+      ;;
     *)
       return 1
       ;;
diff --git a/bin/fm-bootstrap.sh b/bin/fm-bootstrap.sh
index 62568cf5771..9e7fbfdb79a 100755
--- a/bin/fm-bootstrap.sh
+++ b/bin/fm-bootstrap.sh
@@ -845,6 +845,7 @@ install_cmd() {
 manual_install_url() {
   case "$1" in
     herdr) echo "https://herdr.dev" ;;
+    cmux-tui) echo "https://github.com/manaflow-ai/cmux (cmux-tui/)" ;;
     cursor-agent) echo "https://cursor.com/cli" ;;
     *) return 1 ;;
   esac
diff --git a/bin/fm-control-lib.sh b/bin/fm-control-lib.sh
index 820444f58d5..ae76a6c5ebe 100644
--- a/bin/fm-control-lib.sh
+++ b/bin/fm-control-lib.sh
@@ -172,7 +172,7 @@ fm_control_exit_command() {  # <harness>
 fm_control_backend_supports_key() {  # <backend> <key>
   local backend=${1-} key=${2-}
   case "$backend" in
-    tmux|herdr|zellij|cmux)
+    tmux|herdr|zellij|cmux|cmux-tui)
       case "$key" in Escape|Enter|C-c|C-u) return 0 ;; esac
       ;;
     orca)
diff --git a/bin/fm-spawn.sh b/bin/fm-spawn.sh
index 325eefd389c..d23aa0b08cd 100755
--- a/bin/fm-spawn.sh
+++ b/bin/fm-spawn.sh
@@ -975,6 +975,10 @@ if [ "$RELAUNCH" -eq 0 ]; then
     echo "error: backend=cmux does not support --secondmate spawns yet" >&2
     exit 1
   fi
+  if [ "$BACKEND" = cmux-tui ] && [ "$KIND" = secondmate ]; then
+    echo "error: backend=cmux-tui does not support --secondmate spawns yet" >&2
+    exit 1
+  fi
   if [ "$BACKEND" = orca ]; then
     fm_backend_orca_runtime_check || exit 1
   fi
@@ -2077,6 +2081,18 @@ EOF
     fi
     T="$CMUX_WORKSPACE_ID:$CMUX_SURFACE_ID"
     ;;
+  cmux-tui)
+    CMUXTUI_SES=$(fm_backend_cmuxtui_container_ensure) || exit 1
+    CMUXTUI_TASK_IDS=$(fm_backend_cmuxtui_create_task "$W" "$PROJ_ABS") || exit 1
+    read -r CMUXTUI_WORKSPACE_ID CMUXTUI_TERMINAL_ID <<EOF
+$CMUXTUI_TASK_IDS
+EOF
+    if [ -z "$CMUXTUI_WORKSPACE_ID" ] || [ -z "$CMUXTUI_TERMINAL_ID" ]; then
+      echo "error: cmux-tui did not return a workspace/terminal id for $W" >&2
+      exit 1
+    fi
+    T="$CMUXTUI_WORKSPACE_ID:$CMUXTUI_TERMINAL_ID"
+    ;;
   orca)
     set +e
     ORCA_WT_RAW=$(fm_backend_orca_worktree_create "$PROJ_ABS" "$W")
@@ -2122,6 +2138,7 @@ spawn_send_text_line() {  # <target> <text>
     zellij) fm_backend_zellij_send_text_line "$1" "$2" "$W" ;;
     orca) fm_backend_orca_send_text_line "$1" "$2" ;;
     cmux) fm_backend_cmux_send_text_line "$1" "$2" "$W" ;;
+    cmux-tui) fm_backend_cmuxtui_send_text_line "$1" "$2" "$W" ;;
   esac
 }
 spawn_current_path() {  # <target>
@@ -2130,6 +2147,7 @@ spawn_current_path() {  # <target>
     herdr) fm_backend_herdr_current_path "$1" ;;
     zellij) fm_backend_zellij_current_path "$1" "$W" ;;
     cmux) fm_backend_cmux_current_path "$1" "$W" ;;
+    cmux-tui) fm_backend_cmuxtui_current_path "$1" "$W" ;;
   esac
 }
 spawn_send_literal() {  # <target> <text>
@@ -2139,6 +2157,7 @@ spawn_send_literal() {  # <target> <text>
     zellij) fm_backend_zellij_send_literal "$1" "$2" "$W" ;;
     orca) fm_backend_orca_send_literal "$1" "$2" ;;
     cmux) fm_backend_cmux_send_literal "$1" "$2" "$W" ;;
+    cmux-tui) fm_backend_cmuxtui_send_literal "$1" "$2" "$W" ;;
   esac
 }
 spawn_send_key() {  # <target> <key>
@@ -2148,6 +2167,7 @@ spawn_send_key() {  # <target> <key>
     zellij) fm_backend_zellij_send_key "$1" "$2" "$W" ;;
     orca) fm_backend_orca_send_key "$1" "$2" ;;
     cmux) fm_backend_cmux_send_key "$1" "$2" "$W" ;;
+    cmux-tui) fm_backend_cmuxtui_send_key "$1" "$2" "$W" ;;
   esac
 }
 
@@ -2647,7 +2667,7 @@ fi
 preserve_relaunch_meta() {
   awk -F= '
     BEGIN {
-      split("window endpoint_task_id worktree project harness kind mode yolo tasktmp model effort busy_gen spawn_gen traceparent backend herdr_session herdr_workspace_id herdr_tab_id herdr_pane_id zellij_session zellij_tab_id zellij_pane_id orca_worktree_id terminal cmux_workspace_id cmux_surface_id home projects control_relaunch_tx", keys, " ")
+      split("window endpoint_task_id worktree project harness kind mode yolo tasktmp model effort busy_gen spawn_gen traceparent backend herdr_session herdr_workspace_id herdr_tab_id herdr_pane_id zellij_session zellij_tab_id zellij_pane_id orca_worktree_id terminal cmux_workspace_id cmux_surface_id cmuxtui_session cmuxtui_workspace_id cmuxtui_terminal_id home projects control_relaunch_tx", keys, " ")
       for (i in keys) owned[keys[i]] = 1
     }
     !($1 in owned)
@@ -2691,6 +2711,11 @@ preserve_relaunch_meta() {
     echo "cmux_workspace_id=$CMUX_WORKSPACE_ID"
     echo "cmux_surface_id=$CMUX_SURFACE_ID"
   fi
+  if [ "$BACKEND" = cmux-tui ]; then
+    echo "cmuxtui_session=$CMUXTUI_SES"
+    echo "cmuxtui_workspace_id=$CMUXTUI_WORKSPACE_ID"
+    echo "cmuxtui_terminal_id=$CMUXTUI_TERMINAL_ID"
+  fi
   if [ "$KIND" = secondmate ]; then
     echo "home=$PROJ_ABS"
     echo "projects=$SECONDMATE_PROJECTS"

From 023d3e219dde9c9875ea93a0e0627c90f136a0ba Mon Sep 17 00:00:00 2001
From: lawrencecchen <54008264+lawrencecchen@users.noreply.github.com>
Date: Mon, 24 Aug 2026 23:37:56 -0700
Subject: [PATCH 2/3] test(backend): cmux-tui adapter unit suite and
 real-binary smoke

tests/fm-backend-cmux-tui.test.sh: 54 fake-CLI unit tests in the
fm-backend-cmux.test.sh fakebin/command-log shape - version gate, home
session naming, adapter-owned CMUX_TUI_CONFIG export, target parsing, key
normalization, registry/detect/notice wiring (CMUX_TUI_SOCKET and the
legacy CMUX_MUX_SOCKET, innermost-first against tmux/herdr and above the
GUI cmux markers), endpoint validation, create with correlation-key
nonce retry semantics, durable-id target readiness with the exactly-one
label-adoption guard, capture trimming plus contiguous-history append,
send primitives with Enter-failure cleanup, cursor-anchored composer
verdicts (styled=0 degradation, strict blank-row rule, hidden-cursor
fallback), shared submit retry, structured current-path with the
child-pid fallback, native busy-state mapping, guarded kill recovery,
snapshot-based list_live, and the fm-spawn --secondmate refusal.

tests/fm-backend-cmux-tui-smoke.test.sh: 14 live checks against the real
installed binary, all inside one throwaway fm-tui-test-<nonce> session
with a scratch --state dir and adapter-owned config, fm-test- labels
only, and a teardown that stops the session it started (the
tests/cmux-test-safety.sh posture). It proves headless bring-up,
duplicate refusal, label verification, two-step submit, scrollback
capture, the frozen-subshell cwd counterexample via the child pid, the
hook-fed busy transitions, durable-id restart recovery, and
last-workspace close with the session surviving.

tests/fm-backend.test.sh gains one global CMUX_TUI_SOCKET/CMUX_MUX_SOCKET
unset so its detection assertions stay deterministic when the suite
itself runs inside a cmux-tui terminal.
---
 tests/fm-backend-cmux-tui-smoke.test.sh | 224 ++++++
 tests/fm-backend-cmux-tui.test.sh       | 935 ++++++++++++++++++++++++
 tests/fm-backend.test.sh                |   7 +
 3 files changed, 1166 insertions(+)
 create mode 100755 tests/fm-backend-cmux-tui-smoke.test.sh
 create mode 100755 tests/fm-backend-cmux-tui.test.sh

diff --git a/tests/fm-backend-cmux-tui-smoke.test.sh b/tests/fm-backend-cmux-tui-smoke.test.sh
new file mode 100755
index 00000000000..af11104e410
--- /dev/null
+++ b/tests/fm-backend-cmux-tui-smoke.test.sh
@@ -0,0 +1,224 @@
+#!/usr/bin/env bash
+# tests/fm-backend-cmux-tui-smoke.test.sh - real cmux-tui smoke test for the
+# cmux-tui session-provider adapter (bin/backends/cmux-tui.sh), verified
+# against the real 0.1.0 binary (docs/verification/runtime-backends.md
+# "cmux-tui"). Mirrors tests/fm-backend-cmux-smoke.test.sh's structure: the
+# unit suite fakes the CLI, this one talks to the REAL binary.
+#
+# Isolation posture (the tests/cmux-test-safety.sh discipline, made stronger
+# by cmux-tui's real session layer): everything runs inside ONE throwaway
+# per-run session (FM_CMUXTUI_SESSION=fm-tui-test-<nonce>) with its own
+# scratch --state dir and adapter-owned CMUX_TUI_CONFIG, so no call can ever
+# reach an operator session (including the default "main" session). Task
+# labels are fm-test- prefixed, cleanup closes only what this test created,
+# and teardown stops the throwaway session it started and removes its
+# scratch state. Nothing here enumerates-and-closes a shared namespace.
+#
+# Skips cleanly when cmux-tui (or jq) is not installed, so CI/dev machines
+# without the binary are unaffected.
+set -u
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+command -v jq >/dev/null 2>&1 || { echo "skip: jq not found (required by the cmux-tui adapter)"; exit 0; }
+
+TMP_ROOT=$(mktemp -d "${TMPDIR:-/tmp}/fm-cmux-tui-smoke.XXXXXX")
+export FM_HOME="$TMP_ROOT/home"
+mkdir -p "$FM_HOME"
+export FM_CMUXTUI_SESSION="fm-tui-test-$$-$RANDOM"
+export FM_CMUXTUI_STATE="$TMP_ROOT/tui-state"
+export FM_CMUXTUI_CONFIG="$TMP_ROOT/cmux-tui.json"
+unset FM_CMUXTUI_BIN
+
+SESSION_STARTED=0
+cleanup_all() {
+  if [ "$SESSION_STARTED" -eq 1 ]; then
+    fm_backend_cmuxtui_cli server stop --session "$FM_CMUXTUI_SESSION" >/dev/null 2>&1 || true
+  fi
+  rm -rf "$TMP_ROOT"
+}
+fail() { printf 'not ok - %s\n' "$1" >&2; cleanup_all; exit 1; }
+pass() { printf 'ok - %s\n' "$1"; }
+trap cleanup_all EXIT
+
+# shellcheck source=/dev/null
+. "$ROOT/bin/fm-backend.sh"
+fm_backend_source cmux-tui || { echo "skip: could not source the cmux-tui adapter"; exit 0; }
+
+fm_backend_cmuxtui_tool_check >/dev/null 2>&1 || { echo "skip: cmux-tui CLI not found on PATH"; exit 0; }
+fm_backend_cmuxtui_version_check >/dev/null 2>&1 || { echo "skip: installed cmux-tui is older than the verified minimum"; exit 0; }
+
+# --- container_ensure: dedicated headless throwaway session -------------------
+
+SES=$(fm_backend_cmuxtui_container_ensure) || fail "container_ensure failed"
+SESSION_STARTED=1
+[ "$SES" = "$FM_CMUXTUI_SESSION" ] || fail "container_ensure should echo the session name, got '$SES'"
+fm_backend_cmuxtui_server_running || fail "the throwaway session should be running after container_ensure"
+fm_backend_cmuxtui_container_ensure >/dev/null || fail "container_ensure must be idempotent on a running session"
+pass "real cmux-tui: container_ensure starts (and idempotently reuses) the isolated headless session"
+
+# --- create_task + duplicate refusal -------------------------------------------
+
+LABEL="fm-test-smoke1"
+TASK_IDS=$(fm_backend_cmuxtui_create_task "$LABEL" /tmp) || fail "create_task failed"
+read -r WS1 TERM1 <<EOF
+$TASK_IDS
+EOF
+if [ -z "$WS1" ] || [ -z "$TERM1" ]; then
+  fail "create_task did not return workspace/terminal ids"
+fi
+case "$WS1" in ws_*) : ;; *) fail "workspace id should be a typed ws_ id, got '$WS1'" ;; esac
+case "$TERM1" in term_*) : ;; *) fail "terminal id should be a typed term_ id, got '$TERM1'" ;; esac
+TARGET="$WS1:$TERM1"
+
+if fm_backend_cmuxtui_create_task "$LABEL" /tmp >/dev/null 2>&1; then
+  fail "create_task should refuse a duplicate workspace name (cmux-tui itself does not enforce uniqueness)"
+fi
+pass "real cmux-tui: create_task creates a workspace/terminal and refuses a duplicate label"
+
+# --- expected-label verification ------------------------------------------------
+
+fm_backend_cmuxtui_send_key "$TARGET" Escape "$LABEL" \
+  || fail "send_key with a matching expected task label should succeed"
+if fm_backend_cmuxtui_send_key "$TARGET" Escape "fm-test-not-$LABEL" >/dev/null 2>&1; then
+  fail "send_key with a mismatched expected task label should fail"
+fi
+pass "real cmux-tui: expected-label verification accepts the matching workspace and rejects a mismatch"
+
+# --- send_literal + send_key(Enter), the two-step submit form ------------------
+
+sleep 0.5
+fm_backend_cmuxtui_send_literal "$TARGET" 'echo literal-then-key-captain' \
+  || fail "send_literal failed"
+sleep 0.3
+fm_backend_cmuxtui_send_key "$TARGET" Enter || fail "send_key Enter failed"
+sleep 0.7
+out=$(fm_backend_cmuxtui_capture "$TARGET" 20) || fail "capture failed after send_literal+send_key"
+case "$out" in
+  *literal-then-key-captain*) : ;;
+  *) fail "real cmux-tui: send_literal + send_key(Enter) did not submit and echo the line"$'\n'"$out" ;;
+esac
+pass "real cmux-tui: send_literal (unsubmitted) + send_key Enter submit as two steps and the output is capturable"
+
+# --- send_text_line (the composed form) -----------------------------------------
+
+fm_backend_cmuxtui_send_text_line "$TARGET" "echo captain-on-deck-line" \
+  || fail "send_text_line failed"
+sleep 0.7
+out=$(fm_backend_cmuxtui_capture "$TARGET" 20) || fail "capture failed after send_text_line"
+case "$out" in
+  *captain-on-deck-line*) : ;;
+  *) fail "real cmux-tui: send_text_line did not run and echo the line"$'\n'"$out" ;;
+esac
+pass "real cmux-tui: send_text_line composes write+Enter and its output is capturable"
+
+# --- capture beyond the viewport pulls contiguous scrollback --------------------
+
+# shellcheck disable=SC2016 # The $(seq) must reach the terminal literally for ITS shell to expand.
+fm_backend_cmuxtui_send_text_line "$TARGET" 'for i in $(seq 1 60); do echo smoke-scroll-$i; done'
+sleep 1
+out=$(fm_backend_cmuxtui_capture "$TARGET" 80) || fail "large capture failed"
+case "$out" in
+  *smoke-scroll-2*) : ;;
+  *) fail "real cmux-tui: a larger-than-viewport capture did not include scrolled-out history"$'\n'"$out" ;;
+esac
+case "$out" in
+  *smoke-scroll-60*) : ;;
+  *) fail "real cmux-tui: the large capture lost the newest visible rows"$'\n'"$out" ;;
+esac
+pass "real cmux-tui: capture beyond the viewport includes contiguous scrollback plus the live screen"
+
+# --- current_path: structured live cwd, frozen-subshell counterexample ---------
+
+fm_backend_cmuxtui_send_text_line "$TARGET" "cd /tmp"
+sleep 0.5
+p=$(fm_backend_cmuxtui_current_path "$TARGET") || fail "current_path failed"
+case "$p" in
+  */tmp) : ;;
+  *) fail "real cmux-tui: current_path did not report the shell's cwd after a direct cd, got '$p'" ;;
+esac
+pass "real cmux-tui: current_path reads the live cwd after a direct cd"
+
+# The load-bearing case: an integration-free foreground SUBSHELL's own cd
+# (exactly what `treehouse get` opens). The structured cwd field stays frozen
+# at the launch dir; the child pid's OS-level cwd is the live answer.
+fm_backend_cmuxtui_send_text_line "$TARGET" 'env -i /bin/bash --norc'
+sleep 0.8
+fm_backend_cmuxtui_send_text_line "$TARGET" "cd /usr/local"
+sleep 0.5
+p2=$(fm_backend_cmuxtui_current_path "$TARGET") || fail "current_path failed inside a nested subshell"
+case "$p2" in
+  /usr/local) : ;;
+  *) fail "real cmux-tui: current_path did not track an integration-free subshell's own cd (the treehouse-get-shaped case), got '$p2'" ;;
+esac
+pass "real cmux-tui: current_path tracks a foreground subshell's cd through the child pid (structured cwd stays frozen)"
+fm_backend_cmuxtui_send_text_line "$TARGET" 'exit'
+sleep 0.5
+
+# --- composer_state: a plain shell prompt is never a safe injection target -----
+
+cs=$(fm_backend_cmuxtui_composer_state "$TARGET")
+[ "$cs" = unknown ] || fail "a plain shell prompt should classify unknown (no agent composer), got '$cs'"
+pass "real cmux-tui: composer_state reads a plain shell prompt as unknown, never a false empty"
+
+# --- busy_state: native hook-fed agent record -----------------------------------
+
+bs=$(fm_backend_busy_state cmux-tui "$TARGET")
+[ "$bs" = unknown ] || fail "busy_state should report unknown with no agent row, got '$bs'"
+fm_backend_cmuxtui_cli agent report --terminal "$TERM1" --state working --source hook >/dev/null 2>&1 \
+  || fail "agent report (working) failed"
+bs=$(fm_backend_busy_state cmux-tui "$TARGET")
+[ "$bs" = busy ] || fail "busy_state should report busy after a working agent report, got '$bs'"
+fm_backend_cmuxtui_cli agent report --terminal "$TERM1" --state idle --source hook >/dev/null 2>&1 \
+  || fail "agent report (idle) failed"
+bs=$(fm_backend_busy_state cmux-tui "$TARGET")
+[ "$bs" = idle ] || fail "busy_state should report idle after an idle agent report, got '$bs'"
+pass "real cmux-tui: fm_backend_busy_state reads the native hook-fed agent state (unknown -> busy -> idle)"
+
+# --- list_live (id-first recovery discovery) ------------------------------------
+
+live=$(fm_backend_cmuxtui_list_live)
+case "$live" in
+  *"$WS1:$TERM1"*"$LABEL"*) : ;;
+  *) fail "list_live did not report the live task workspace with its ids and label"$'\n'"--- got ---"$'\n'"$live" ;;
+esac
+pass "real cmux-tui: list_live discovers the live task workspace with durable ids and its label"
+
+# --- durable ids across a server restart ----------------------------------------
+
+fm_backend_cmuxtui_cli server stop --session "$FM_CMUXTUI_SESSION" >/dev/null 2>&1 \
+  || fail "server stop failed"
+sleep 1
+if fm_backend_cmuxtui_server_running; then
+  fail "the session should be down after server stop"
+fi
+fm_backend_cmuxtui_container_ensure >/dev/null || fail "container_ensure failed to restart from durable state"
+fm_backend_cmuxtui_target_ready "$TARGET" "$LABEL" \
+  || fail "the recorded workspace:terminal target should survive a server restart (durable ids)"
+out=$(fm_backend_cmuxtui_capture "$TARGET" 5) || fail "capture failed on the restored terminal"
+[ -n "$out" ] || fail "the restored terminal should produce a readable screen"
+pass "real cmux-tui: the recorded target survives a server restart - durable ids are the recovery authority"
+
+# --- kill: whole-workspace close, last workspace included ------------------------
+
+fm_backend_cmuxtui_kill "$TARGET" "" "$LABEL"
+sleep 0.5
+STILL_LIVE=$(fm_backend_cmuxtui_cli workspace list --json 2>/dev/null | jq -r --arg id "$WS1" '.[]? | select(.id == $id) | .id')
+[ -z "$STILL_LIVE" ] || fail "kill did not remove the task workspace"
+fm_backend_cmuxtui_server_running || fail "the session server should keep running after closing its last workspace"
+fm_backend_cmuxtui_kill "$TARGET" || fail "kill on an already-dead target must stay best-effort (never fail)"
+pass "real cmux-tui: kill removes the whole workspace (last one included), stays idempotent, and the session survives"
+
+# --- teardown: stop the throwaway session ----------------------------------------
+
+fm_backend_cmuxtui_cli server stop --session "$FM_CMUXTUI_SESSION" >/dev/null 2>&1 \
+  || fail "final server stop failed"
+SESSION_STARTED=0
+sleep 0.5
+if fm_backend_cmuxtui_server_running; then
+  fail "the throwaway session should be stopped at teardown"
+fi
+pass "real cmux-tui: the throwaway session is stopped and its scratch state removed"
+
+cleanup_all
+trap - EXIT
diff --git a/tests/fm-backend-cmux-tui.test.sh b/tests/fm-backend-cmux-tui.test.sh
new file mode 100755
index 00000000000..584378652a4
--- /dev/null
+++ b/tests/fm-backend-cmux-tui.test.sh
@@ -0,0 +1,935 @@
+#!/usr/bin/env bash
+# tests/fm-backend-cmux-tui.test.sh - fake-cmux-tui-CLI unit tests for the
+# cmux-tui session-provider adapter (bin/backends/cmux-tui.sh), verified
+# against the real cmux-tui 0.1.0 binary
+# (docs/verification/runtime-backends.md "cmux-tui"). Mirrors
+# tests/fm-backend-cmux.test.sh's fakebin/command-log convention: a small,
+# LOG-based, canned-response fake `cmux-tui` + real `jq` (jq is a real
+# required tool for this backend, not faked). The real-binary smoke test
+# lives in tests/fm-backend-cmux-tui-smoke.test.sh, gated on the cmux-tui
+# binary actually being installed.
+set -u
+
+# shellcheck source=tests/lib.sh
+. "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+command -v jq >/dev/null 2>&1 || { echo "skip: jq not found (required by the cmux-tui adapter)"; exit 0; }
+
+TMP_ROOT=$(fm_test_tmproot fm-backend-cmux-tui-tests)
+
+# The adapter's own env knobs must not leak in from the environment this
+# suite happens to run inside (e.g. a developer shell inside cmux-tui).
+unset FM_CMUXTUI_BIN FM_CMUXTUI_SESSION FM_CMUXTUI_CONFIG FM_CMUXTUI_STATE
+
+# make_cmuxtui_fakebin: a `cmux-tui` stub that logs every invocation (one
+# line, unit-separated args, prefixed with the exported CMUX_TUI_CONFIG, to
+# $FM_CMUXTUI_LOG) and returns the canned response for that call read from
+# $FM_CMUXTUI_RESPONSES/<n>.out, consumed IN ORDER. A missing response file
+# means "succeed with empty stdout". `--version` and `server status` are
+# handled specially (not call-counted, not consuming the ordered queue),
+# mirroring the cmux fake's version/ping special-casing. An <n>.exit file
+# sets that call's exit code, with any <n>.out still printed first (the real
+# CLI prints its typed error JSON alongside a nonzero exit).
+make_cmuxtui_fakebin() {  # <dir> -> echoes fakebin dir
+  local dir=$1 fb="$1/fakebin"
+  mkdir -p "$fb"
+  cat > "$fb/cmux-tui" <<'SH'
+#!/usr/bin/env bash
+set -u
+LOG="${FM_CMUXTUI_LOG:?}"
+RESP="${FM_CMUXTUI_RESPONSES:?}"
+COUNT_FILE="$RESP/.count"
+{
+  printf 'CMUX_TUI_CONFIG=%s' "${CMUX_TUI_CONFIG:-}"
+  for a in "$@"; do printf '\x1f%s' "$a"; done
+  printf '\n'
+} >> "$LOG"
+
+if [ "${1:-}" = --version ]; then
+  printf 'cmux %s (4471965b12d19914793f46f96322fff5815da010; ghostty f76c132e)\n' "${FM_CMUXTUI_FAKE_VERSION:-0.1.0}"
+  exit 0
+fi
+if [ "${1:-}" = server ] && [ "${2:-}" = status ]; then
+  exit "${FM_CMUXTUI_FAKE_STATUS_EXIT:-0}"
+fi
+
+next=$(( $(cat "$COUNT_FILE" 2>/dev/null || echo 0) + 1 ))
+echo "$next" > "$COUNT_FILE"
+[ -f "$RESP/$next.out" ] && cat "$RESP/$next.out"
+if [ -f "$RESP/$next.exit" ]; then
+  exit "$(cat "$RESP/$next.exit")"
+fi
+exit 0
+SH
+  chmod +x "$fb/cmux-tui"
+  printf '%s\n' "$fb"
+}
+
+# The typed opaque ids the real CLI returns (docs/verification "cmux-tui").
+WS_A=ws_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+WS_B=ws_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
+TERM_A=term_11111111111111111111111111111111
+TERM_B=term_22222222222222222222222222222222
+TARGET_A="$WS_A:$TERM_A"
+
+cmuxtui_workspace_list_response() {  # <dir> <n> [<id> <name>]...
+  local dir=$1 n=$2 json first=1
+  shift 2
+  json='['
+  while [ $# -ge 2 ]; do
+    [ "$first" -eq 1 ] || json="$json,"
+    json="$json{\"id\":\"$1\",\"name\":\"$2\",\"focused\":false,\"index\":0}"
+    first=0
+    shift 2
+  done
+  json="$json]"
+  printf '%s' "$json" > "$dir/responses/$n.out"
+}
+
+cmuxtui_workspace_show_response() {  # <dir> <n> <id> <name>
+  printf '{"id":"%s","name":"%s","focused":true,"index":0}' "$3" "$4" > "$1/responses/$2.out"
+}
+
+cmuxtui_terminal_show_response() {  # <dir> <n> <term_id>
+  printf '{"id":"%s","lifecycle":"running","running":true,"rows":24,"cols":80}' "$3" > "$1/responses/$2.out"
+}
+
+cmuxtui_screen_read_response() {  # <dir> <n> <text> [cursor_row] [cursor_visible]
+  jq -n --arg t "$3" --argjson cy "${4:-0}" --argjson vis "${5:-true}" \
+    '{text:$t, cursor_row:$cy, cursor_col:2, cursor_visible:$vis, rows:24, cols:80}' \
+    > "$1/responses/$2.out"
+}
+
+cmuxtui_create_response() {  # <dir> <n> <kind> <id>
+  printf '{"generation":"g1","replayed":false,"revision":"1","value":{"kind":"%s","%s_id":"%s"}}' \
+    "$3" "$3" "$4" > "$1/responses/$2.out"
+}
+
+cmuxtui_snapshot_response() {  # <dir> <n> <ws_id> <ws_name> <tab_id> <term_id>
+  jq -n --arg ws "$3" --arg name "$4" --arg tab "$5" --arg term "$6" '{
+    workspaces: [{id:$ws, name:$name, focused:true, index:0}],
+    screens: [{id:"screen_1", workspace_id:$ws, layout:{root:{kind:"leaf", tab_ids:[$tab]}}}],
+    tabs: [{id:$tab, content_kind:"terminal", content_id:$term}]
+  }' > "$1/responses/$2.out"
+}
+
+cmuxtui_agent_list_response() {  # <dir> <n> <term_id> <state> <updated_at_ms>
+  jq -n --arg t "$3" --arg s "$4" --arg u "$5" \
+    '[{id:"agent_1", terminal_id:$t, state:$s, source:"hook", updated_at_ms:$u}]' \
+    > "$1/responses/$2.out"
+}
+
+cmuxtui_typed_error_response() {  # <dir> <n> <code> <retryable> <exit>
+  printf '{"code":"%s","details":{},"message":"fixture error","retryable":%s}' "$3" "$4" > "$1/responses/$2.out"
+  printf '%s' "$5" > "$1/responses/$2.exit"
+}
+
+# run_adapter <dir> <fakebin> <script...>: source the adapter in an isolated
+# home with the fake CLI first on PATH and a pinned test session name.
+run_adapter() {  # <dir> <fb> <bash -c body>
+  local dir=$1 fb=$2 body=$3
+  PATH="$fb:$PATH" FM_HOME="$dir" FM_CMUXTUI_SESSION=fm-tui-test-unit \
+    FM_CMUXTUI_CONFIG="$dir/cmux-tui.json" FM_CMUXTUI_STATE="$dir/tui-state" \
+    FM_CMUXTUI_LOG="$dir/log" FM_CMUXTUI_RESPONSES="$dir/responses" \
+    bash -c ". \"\$0/bin/backends/cmux-tui.sh\"; $body" "$ROOT"
+}
+
+# --- version_check / tool_check ----------------------------------------------
+
+test_version_check_accepts_current_version() {
+  local dir fb
+  dir="$TMP_ROOT/version-ok"; mkdir -p "$dir/responses"
+  fb=$(make_cmuxtui_fakebin "$dir")
+  FM_CMUXTUI_FAKE_VERSION=0.1.0 run_adapter "$dir" "$fb" 'fm_backend_cmuxtui_version_check' \
+    || fail "version_check should accept 0.1.0 (the verified minimum)"
+  pass "fm_backend_cmuxtui_version_check: accepts the verified minimum (0.1.0)"
+}
+
+test_version_check_accepts_newer_version() {
+  local dir fb
+  dir="$TMP_ROOT/version-newer"; mkdir -p "$dir/responses"
+  fb=$(make_cmuxtui_fakebin "$dir")
+  FM_CMUXTUI_FAKE_VERSION=1.3.0 run_adapter "$dir" "$fb" 'fm_backend_cmuxtui_version_check' \
+    || fail "version_check should accept a newer version (1.3.0)"
+  pass "fm_backend_cmuxtui_version_check: accepts a newer version (1.3.0)"
+}
+
+test_version_check_refuses_old_version() {
+  local dir fb out status
+  dir="$TMP_ROOT/version-old"; mkdir -p "$dir/responses"
+  fb=$(make_cmuxtui_fakebin "$dir")
+  out=$(FM_CMUXTUI_FAKE_VERSION=0.0.9 run_adapter "$dir" "$fb" 'fm_backend_cmuxtui_version_check' 2>&1)
+  status=$?
+  [ "$status" -ne 0 ] || fail "version_check should refuse 0.0.9 (below the 0.1 minimum)"
+  assert_contains "$out" "0.0.9" "version_check error did not name the rejected version"
+  pass "fm_backend_cmuxtui_version_check: refuses an old version loudly"
+}
+
+test_version_check_refuses_missing_binary() {
+  local dir out status
+  dir="$TMP_ROOT/version-missing"; mkdir -p "$dir/empty-fakebin"
+  out=$( PATH="$dir/empty-fakebin:/usr/bin:/bin" FM_HOME="$dir" \
+    bash -c '. "$0/bin/backends/cmux-tui.sh"; fm_backend_cmuxtui_version_check' "$ROOT" 2>&1 )
+  status=$?
+  [ "$status" -ne 0 ] || fail "version_check should refuse when cmux-tui is not installed"
+  assert_contains "$out" "not found" "version_check did not report cmux-tui as missing"
+  pass "fm_backend_cmuxtui_version_check: refuses loudly when cmux-tui is not on PATH"
+}
+
+test_bin_honors_override() {
+  local dir out
+  dir="$TMP_ROOT/bin-override"; mkdir -p "$dir"
+  out=$( FM_CMUXTUI_BIN=/opt/custom/cmux-tui FM_HOME="$dir" \
+    bash -c '. "$0/bin/backends/cmux-tui.sh"; fm_backend_cmuxtui_bin' "$ROOT" )
+  [ "$out" = /opt/custom/cmux-tui ] || fail "fm_backend_cmuxtui_bin should honor FM_CMUXTUI_BIN, got '$out'"
+  pass "fm_backend_cmuxtui_bin: FM_CMUXTUI_BIN overrides PATH resolution"
+}
+
+# --- session naming, config isolation ----------------------------------------
+
+test_session_name_is_home_scoped() {
+  local dir out expected
+  dir="$TMP_ROOT/session-name"; mkdir -p "$dir"
+  expected="fm-$(FM_HOME="$dir" FM_ROOT="$dir" bash -c '. "$0/bin/fm-backend-hometag-lib.sh"; fm_backend_hometag' "$ROOT")"
+  out=$( FM_HOME="$dir" FM_ROOT_OVERRIDE="$dir" \
+    bash -c '. "$0/bin/backends/cmux-tui.sh"; fm_backend_cmuxtui_session' "$ROOT" )
+  [ "$out" = "$expected" ] || fail "default session should be $expected, got '$out'"
+  case "$out" in fm-firstmate-*) : ;; *) fail "primary session should carry the firstmate hometag, got '$out'" ;; esac
+  pass "fm_backend_cmuxtui_session: defaults to the home-scoped fm-<hometag> session"
+}
+
+test_session_name_override() {
+  local dir out
+  dir="$TMP_ROOT/session-override"; mkdir -p "$dir"
+  out=$( FM_HOME="$dir" FM_CMUXTUI_SESSION=fm-tui-test-x \
+    bash -c '. "$0/bin/backends/cmux-tui.sh"; fm_backend_cmuxtui_session' "$ROOT" )
+  [ "$out" = fm-tui-test-x ] || fail "FM_CMUXTUI_SESSION should override the session name, got '$out'"
+  pass "fm_backend_cmuxtui_session: FM_CMUXTUI_SESSION overrides for test isolation"
+}
+
+test_cli_exports_adapter_owned_config() {
+  local dir fb
+  dir="$TMP_ROOT/config-isolation"; mkdir -p "$dir/responses"
+  fb=$(make_cmuxtui_fakebin "$dir")
+  cmuxtui_workspace_list_response "$dir" 1
+  run_adapter "$dir" "$fb" 'fm_backend_cmuxtui_cli workspace list --json' >/dev/null
+  assert_contains "$(cat "$dir/log")" "CMUX_TUI_CONFIG=$dir/cmux-tui.json" \
+    "fm_backend_cmuxtui_cli did not export the adapter-owned CMUX_TUI_CONFIG"
+  [ -f "$dir/cmux-tui.json" ] || fail "the adapter-owned config file was not created"
+  [ "$(cat "$dir/cmux-tui.json")" = "{}" ] || fail "the adapter-owned config should be an empty JSON object"
+  assert_contains "$(cat "$dir/log")" $'\x1f''--session'$'\x1f''fm-tui-test-unit' \
+    "fm_backend_cmuxtui_cli did not route through the explicit home session"
+  pass "fm_backend_cmuxtui_cli: exports the adapter-owned config and the explicit --session route"
+}
+
+# --- target parsing, key normalization ----------------------------------------
+
+test_parse_target() {
+  ( . "$ROOT/bin/backends/cmux-tui.sh"
+    fm_backend_cmuxtui_parse_target "$TARGET_A" || exit 1
+    [ "$FM_BACKEND_CMUXTUI_WORKSPACE" = "$WS_A" ] || { echo "workspace mismatch: $FM_BACKEND_CMUXTUI_WORKSPACE" >&2; exit 1; }
+    [ "$FM_BACKEND_CMUXTUI_TERMINAL" = "$TERM_A" ] || { echo "terminal mismatch: $FM_BACKEND_CMUXTUI_TERMINAL" >&2; exit 1; }
+    fm_backend_cmuxtui_parse_target "no-colon-here" && exit 1
+    exit 0
+  ) || fail "fm_backend_cmuxtui_parse_target did not split workspace:terminal correctly"
+  pass "fm_backend_cmuxtui_parse_target: splits '<workspace_id>:<terminal_id>' on the first colon"
+}
+
+test_normalize_key() {
+  ( . "$ROOT/bin/backends/cmux-tui.sh"
+    [ "$(fm_backend_cmuxtui_normalize_key Enter)" = enter ] || { echo "Enter failed" >&2; exit 1; }
+    [ "$(fm_backend_cmuxtui_normalize_key Escape)" = escape ] || { echo "Escape failed" >&2; exit 1; }
+    [ "$(fm_backend_cmuxtui_normalize_key C-c)" = ctrl+c ] || { echo "C-c failed" >&2; exit 1; }
+    [ "$(fm_backend_cmuxtui_normalize_key C-d)" = ctrl+d ] || { echo "C-d failed" >&2; exit 1; }
+    [ "$(fm_backend_cmuxtui_normalize_key C-u)" = ctrl+u ] || { echo "C-u failed" >&2; exit 1; }
+    [ "$(fm_backend_cmuxtui_normalize_key Tab)" = tab ] || { echo "Tab failed" >&2; exit 1; }
+    [ "$(fm_backend_cmuxtui_normalize_key Up)" = up ] || { echo "Up failed" >&2; exit 1; }
+    [ "$(fm_backend_cmuxtui_normalize_key Down)" = down ] || { echo "Down failed" >&2; exit 1; }
+  ) || fail "fm_backend_cmuxtui_normalize_key did not map firstmate's key vocabulary to cmux-tui's verified chords"
+  pass "fm_backend_cmuxtui_normalize_key: Enter/Escape/C-c/C-d/C-u/Tab/Up/Down map to verified lowercase chords"
+}
+
+# --- dispatch wiring and detection (fm-backend.sh) -----------------------------
+
+test_dispatch_routes_cmuxtui_backend() {
+  fm_backend_validate cmux-tui 2>/dev/null || fail "fm_backend_validate should accept cmux-tui"
+  fm_backend_validate_spawn cmux-tui 2>/dev/null || fail "fm_backend_validate_spawn should accept cmux-tui"
+  [ "$(fm_backend_required_tools cmux-tui)" = "cmux-tui jq treehouse" ] \
+    || fail "fm_backend_required_tools should be 'cmux-tui jq treehouse'"
+  pass "fm-backend.sh: cmux-tui is known, spawn-capable, and owns its tool delta"
+}
+
+test_detect_cmuxtui_socket_marker() {
+  local out
+  out=$(unset TMUX HERDR_ENV CMUX_MUX_SOCKET; CMUX_TUI_SOCKET=/tmp/fake.sock fm_backend_detect) \
+    || fail "fm_backend_detect should succeed when CMUX_TUI_SOCKET is set"
+  [ "$out" = cmux-tui ] || fail "fm_backend_detect should report cmux-tui for CMUX_TUI_SOCKET alone, got '$out'"
+  pass "fm_backend_detect: CMUX_TUI_SOCKET alone selects cmux-tui"
+}
+
+test_detect_cmuxtui_legacy_marker() {
+  local out
+  out=$(unset TMUX HERDR_ENV CMUX_TUI_SOCKET; CMUX_MUX_SOCKET=/tmp/fake.sock fm_backend_detect) \
+    || fail "fm_backend_detect should succeed when legacy CMUX_MUX_SOCKET is set"
+  [ "$out" = cmux-tui ] || fail "fm_backend_detect should report cmux-tui for legacy CMUX_MUX_SOCKET, got '$out'"
+  pass "fm_backend_detect: the legacy CMUX_MUX_SOCKET alias also selects cmux-tui"
+}
+
+test_detect_inner_multiplexers_win_over_cmuxtui() {
+  local out
+  out=$(unset HERDR_ENV; TMUX='fake,1,0' CMUX_TUI_SOCKET=/tmp/fake.sock fm_backend_detect) \
+    || fail "fm_backend_detect should succeed with tmux and cmux-tui markers present"
+  [ "$out" = tmux ] || fail "tmux nested inside cmux-tui must win, got '$out'"
+  out=$(unset TMUX; HERDR_ENV=1 CMUX_TUI_SOCKET=/tmp/fake.sock fm_backend_detect) \
+    || fail "fm_backend_detect should succeed with herdr and cmux-tui markers present"
+  [ "$out" = herdr ] || fail "herdr nested inside cmux-tui must win, got '$out'"
+  pass "fm_backend_detect: tmux/herdr nested inside cmux-tui resolve innermost-first"
+}
+
+test_detect_cmuxtui_wins_over_gui_cmux_marker() {
+  # A cmux-tui session started inside a cmux GUI tab inherits the GUI's
+  # CMUX_WORKSPACE_ID into its terminals (verified live), so the inner
+  # cmux-tui marker must win over the outer GUI app's.
+  local out
+  out=$(unset TMUX HERDR_ENV; CMUX_TUI_SOCKET=/tmp/fake.sock CMUX_WORKSPACE_ID=fake-uuid fm_backend_detect) \
+    || fail "fm_backend_detect should succeed with cmux-tui and cmux GUI markers present"
+  [ "$out" = cmux-tui ] || fail "cmux-tui inside the cmux GUI app must resolve to cmux-tui, got '$out'"
+  pass "fm_backend_detect: CMUX_TUI_SOCKET wins over the inherited GUI CMUX_WORKSPACE_ID"
+}
+
+test_backend_name_notices_autodetected_cmuxtui() {
+  local dir out errfile
+  dir="$TMP_ROOT/name-notice"; mkdir -p "$dir/config-empty"
+  errfile="$dir/stderr"
+  out=$(unset TMUX HERDR_ENV; CMUX_TUI_SOCKET=/tmp/fake.sock FM_BACKEND='' FM_BACKEND_CONFIG_DIR="$dir/config-empty" fm_backend_name 2>"$errfile")
+  [ "$out" = cmux-tui ] || fail "fm_backend_name should auto-detect cmux-tui, got '$out'"
+  assert_contains "$(cat "$errfile")" "EXPERIMENTAL cmux-tui backend" \
+    "auto-detected cmux-tui should print the loud experimental notice"
+  assert_contains "$(cat "$errfile")" "CMUX_TUI_SOCKET" \
+    "the notice should name the winning signal"
+  pass "fm_backend_name: auto-detected cmux-tui prints the experimental notice naming the signal"
+}
+
+test_dispatch_busy_state_routes_cmuxtui() {
+  local dir fb out
+  dir="$TMP_ROOT/dispatch-busy"; mkdir -p "$dir/responses"
+  fb=$(make_cmuxtui_fakebin "$dir")
+  cmuxtui_agent_list_response "$dir" 1 "$TERM_A" working 1000
+  out=$( PATH="$fb:$PATH" FM_HOME="$dir" FM_CMUXTUI_SESSION=fm-tui-test-unit \
+    FM_CMUXTUI_CONFIG="$dir/cmux-tui.json" FM_CMUXTUI_LOG="$dir/log" FM_CMUXTUI_RESPONSES="$dir/responses" \
+    bash -c '. "$0/bin/fm-backend.sh"; fm_backend_busy_state cmux-tui "$1"' "$ROOT" "$TARGET_A" )
+  [ "$out" = busy ] || fail "fm_backend_busy_state should route cmux-tui to its native agent read, got '$out'"
+  pass "fm_backend_busy_state: routes cmux-tui to the native agent-state classifier"
+}
+
+test_endpoint_validation_accepts_and_refuses() {
+  local dir meta
+  dir="$TMP_ROOT/endpoint-validation"; mkdir -p "$dir"
+  meta="$dir/task1.meta"
+  {
+    echo "window=$TARGET_A"
+    echo "endpoint_task_id=task1"
+    echo "worktree=/tmp/wt"
+    echo "project=/tmp/proj"
+    echo "backend=cmux-tui"
+    echo "cmuxtui_session=fm-tui-test-unit"
+    echo "cmuxtui_workspace_id=$WS_A"
+    echo "cmuxtui_terminal_id=$TERM_A"
+  } > "$meta"
+  fm_backend_validate_task_endpoint "$meta" task1 2>/dev/null \
+    || fail "endpoint validation should accept a well-formed cmux-tui record"
+  [ "$FM_BACKEND_VALIDATED_BACKEND" = cmux-tui ] || fail "validated backend should be cmux-tui"
+  [ "$FM_BACKEND_VALIDATED_TARGET" = "$TARGET_A" ] || fail "validated target should be the recorded window"
+  meta="$dir/task2.meta"
+  {
+    echo "window=$WS_B:$TERM_B"
+    echo "endpoint_task_id=task2"
+    echo "worktree=/tmp/wt"
+    echo "project=/tmp/proj"
+    echo "backend=cmux-tui"
+    echo "cmuxtui_session=fm-tui-test-unit"
+    echo "cmuxtui_workspace_id=$WS_A"
+    echo "cmuxtui_terminal_id=$TERM_A"
+  } > "$meta"
+  if fm_backend_validate_task_endpoint "$meta" task2 2>/dev/null; then
+    fail "endpoint validation should refuse a window that disagrees with the recorded id pair"
+  fi
+  pass "fm_backend_validate_task_endpoint: accepts a consistent cmux-tui record and refuses a divergent one"
+}
+
+# --- create_task: duplicate refusal, id resolution, correlation keys ----------
+
+test_create_task_refuses_duplicate_label() {
+  local dir fb out status
+  dir="$TMP_ROOT/dup-task"; mkdir -p "$dir/responses"
+  cmuxtui_workspace_list_response "$dir" 1 "$WS_A" fm-dup1
+  fb=$(make_cmuxtui_fakebin "$dir")
+  out=$(run_adapter "$dir" "$fb" 'fm_backend_cmuxtui_create_task fm-dup1 /tmp/proj' 2>&1)
+  status=$?
+  [ "$status" -ne 0 ] || fail "create_task should refuse an existing workspace name (cmux-tui itself does not enforce uniqueness)"
+  assert_contains "$out" "already exists" "create_task did not report the duplicate name"
+  pass "fm_backend_cmuxtui_create_task: refuses a duplicate workspace name"
+}
+
+test_create_task_creates_and_parses_ids() {
+  local dir fb out log
+  dir="$TMP_ROOT/create-task"; mkdir -p "$dir/responses"
+  cmuxtui_workspace_list_response "$dir" 1
+  cmuxtui_create_response "$dir" 2 workspace "$WS_A"
+  cmuxtui_create_response "$dir" 3 terminal "$TERM_A"
+  fb=$(make_cmuxtui_fakebin "$dir")
+  out=$(run_adapter "$dir" "$fb" 'fm_backend_cmuxtui_create_task fm-newtask /tmp/proj')
+  [ "$out" = "$WS_A $TERM_A" ] || fail "create_task should echo '<workspace_id> <terminal_id>', got '$out'"
+  log=$(cat "$dir/log")
+  assert_contains "$log" $'\x1f''workspace'$'\x1f''create'$'\x1f''--name'$'\x1f''fm-newtask'$'\x1f''--empty' \
+    "create_task did not create an empty named workspace"
+  assert_contains "$log" $'\x1f''tab'$'\x1f''create'$'\x1f''terminal'$'\x1f''--workspace'$'\x1f'"$WS_A"$'\x1f''--cwd'$'\x1f''/tmp/proj' \
+    "create_task did not create the terminal tab with the task cwd"
+  assert_contains "$log" $'\x1f''--correlation-key'$'\x1f' \
+    "create_task's mutations did not carry a correlation key"
+  pass "fm_backend_cmuxtui_create_task: creates workspace+terminal and echoes both ids"
+}
+
+test_mutate_retries_indeterminate_with_same_key() {
+  local dir fb out keys
+  dir="$TMP_ROOT/mutate-retry"; mkdir -p "$dir/responses"
+  # 1: workspace create -> typed retryable mutation.indeterminate error
+  cmuxtui_typed_error_response "$dir" 1 mutation.indeterminate true 1
+  # 2: the retry succeeds
+  cmuxtui_create_response "$dir" 2 workspace "$WS_A"
+  fb=$(make_cmuxtui_fakebin "$dir")
+  out=$(run_adapter "$dir" "$fb" 'fm_backend_cmuxtui_mutate workspace create --name fm-x --empty')
+  assert_contains "$out" "$WS_A" "mutate should return the retry's successful response"
+  keys=$(grep -o -e $'--correlation-key\x1f[^\x1f]*' "$dir/log" | sort -u | wc -l | tr -d '[:space:]')
+  [ "$keys" = 1 ] || fail "the retry must reuse the SAME correlation key (found $keys distinct keys)"
+  [ "$(grep -c $'\x1f''workspace'$'\x1f''create' "$dir/log")" = 2 ] \
+    || fail "mutate should have attempted the create exactly twice"
+  pass "fm_backend_cmuxtui_mutate: retries a mutation.indeterminate error once with the same correlation key"
+}
+
+test_mutate_does_not_retry_terminal_errors() {
+  local dir fb status
+  dir="$TMP_ROOT/mutate-no-retry"; mkdir -p "$dir/responses"
+  cmuxtui_typed_error_response "$dir" 1 validation.invalid false 1
+  fb=$(make_cmuxtui_fakebin "$dir")
+  run_adapter "$dir" "$fb" 'fm_backend_cmuxtui_mutate workspace create --name fm-x --empty' >/dev/null 2>&1
+  status=$?
+  [ "$status" -ne 0 ] || fail "mutate should propagate a non-retryable typed error"
+  [ "$(grep -c $'\x1f''workspace'$'\x1f''create' "$dir/log")" = 1 ] \
+    || fail "a non-retryable error must not be retried"
+  pass "fm_backend_cmuxtui_mutate: a non-retryable typed error fails once, with no blind retry"
+}
+
+# --- target_ready: durable ids first, guarded label recovery ------------------
+
+test_target_ready_fails_when_terminal_absent() {
+  local dir fb status
+  dir="$TMP_ROOT/ready-absent"; mkdir -p "$dir/responses"
+  cmuxtui_typed_error_response "$dir" 1 selector.not_found false 1
+  fb=$(make_cmuxtui_fakebin "$dir")
+  run_adapter "$dir" "$fb" "fm_backend_cmuxtui_target_ready $TARGET_A"
+  status=$?
+  [ "$status" -ne 0 ] || fail "target_ready should fail when terminal show reports selector.not_found"
+  pass "fm_backend_cmuxtui_target_ready: fails when the terminal id is gone"
+}
+
+test_target_ready_verifies_expected_label() {
+  local dir fb
+  dir="$TMP_ROOT/ready-label-ok"; mkdir -p "$dir/responses"
+  cmuxtui_workspace_show_response "$dir" 1 "$WS_A" fm-label
+  cmuxtui_terminal_show_response "$dir" 2 "$TERM_A"
+  fb=$(make_cmuxtui_fakebin "$dir")
+  run_adapter "$dir" "$fb" "fm_backend_cmuxtui_target_ready $TARGET_A fm-label" \
+    || fail "target_ready should succeed when the workspace name matches the expected label"
+  pass "fm_backend_cmuxtui_target_ready: verifies the workspace name against the expected label"
+}
+
+test_target_ready_rejects_label_mismatch() {
+  local dir fb status
+  dir="$TMP_ROOT/ready-label-mismatch"; mkdir -p "$dir/responses"
+  cmuxtui_workspace_show_response "$dir" 1 "$WS_A" not-the-task
+  fb=$(make_cmuxtui_fakebin "$dir")
+  run_adapter "$dir" "$fb" "fm_backend_cmuxtui_target_ready $TARGET_A fm-label"
+  status=$?
+  [ "$status" -ne 0 ] || fail "target_ready should reject a workspace id now carrying a different name"
+  assert_not_contains "$(cat "$dir/log")" $'\x1f''terminal'$'\x1f' \
+    "target_ready should not touch the terminal after a label mismatch"
+  pass "fm_backend_cmuxtui_target_ready: rejects a workspace id reused under a different name"
+}
+
+test_target_ready_adopts_unambiguous_label_when_id_gone() {
+  local dir fb out
+  dir="$TMP_ROOT/ready-adopt"; mkdir -p "$dir/responses"
+  # 1: workspace show for the stale id -> typed not-found (empty name)
+  cmuxtui_typed_error_response "$dir" 1 selector.not_found false 1
+  # 2: workspace list -> exactly one workspace carries the label
+  cmuxtui_workspace_list_response "$dir" 2 "$WS_B" fm-label
+  # 3: snapshot -> that workspace's terminal
+  cmuxtui_snapshot_response "$dir" 3 "$WS_B" fm-label tab_1 "$TERM_B"
+  fb=$(make_cmuxtui_fakebin "$dir")
+  out=$(run_adapter "$dir" "$fb" "fm_backend_cmuxtui_target_ready $TARGET_A fm-label && printf '%s:%s' \"\$FM_BACKEND_CMUXTUI_WORKSPACE\" \"\$FM_BACKEND_CMUXTUI_TERMINAL\"")
+  [ "$out" = "$WS_B:$TERM_B" ] || fail "target_ready should adopt the unambiguous live label's ids, got '$out'"
+  pass "fm_backend_cmuxtui_target_ready: adopts by name only when exactly one live workspace carries the label"
+}
+
+test_target_ready_refuses_ambiguous_label() {
+  local dir fb status
+  dir="$TMP_ROOT/ready-ambiguous"; mkdir -p "$dir/responses"
+  cmuxtui_typed_error_response "$dir" 1 selector.not_found false 1
+  cmuxtui_workspace_list_response "$dir" 2 "$WS_B" fm-label ws_cccccccccccccccccccccccccccccccc fm-label
+  fb=$(make_cmuxtui_fakebin "$dir")
+  run_adapter "$dir" "$fb" "fm_backend_cmuxtui_target_ready $TARGET_A fm-label"
+  status=$?
+  [ "$status" -ne 0 ] || fail "target_ready must refuse adoption when two live workspaces share the label"
+  pass "fm_backend_cmuxtui_target_ready: refuses label adoption when the name is ambiguous"
+}
+
+# --- capture / send primitives -------------------------------------------------
+
+test_capture_trims_screen_locally() {
+  local dir fb out
+  dir="$TMP_ROOT/capture"; mkdir -p "$dir/responses"
+  cmuxtui_terminal_show_response "$dir" 1 "$TERM_A"
+  cmuxtui_screen_read_response "$dir" 2 $'line one\nline two\nline three\nline four'
+  fb=$(make_cmuxtui_fakebin "$dir")
+  out=$(run_adapter "$dir" "$fb" "fm_backend_cmuxtui_capture $TARGET_A 2")
+  [ "$out" = $'line three\nline four' ] || fail "capture should trim to the last N lines locally, got '$out'"
+  assert_not_contains "$(cat "$dir/log")" $'\x1f''history' \
+    "a request smaller than the visible screen should not fetch history"
+  pass "fm_backend_cmuxtui_capture: trims the visible screen to N lines locally"
+}
+
+test_capture_appends_history_for_large_requests() {
+  local dir fb out
+  dir="$TMP_ROOT/capture-history"; mkdir -p "$dir/responses"
+  cmuxtui_terminal_show_response "$dir" 1 "$TERM_A"
+  cmuxtui_screen_read_response "$dir" 2 $'screen one\nscreen two'
+  jq -n '{next: null, rows: [
+    {row:0, runs:[{attrs:0, text:"hist one   "}]},
+    {row:1, runs:[{attrs:0, text:"hist "},{attrs:1, text:"two"}]}
+  ]}' > "$dir/responses/3.out"
+  fb=$(make_cmuxtui_fakebin "$dir")
+  out=$(run_adapter "$dir" "$fb" "fm_backend_cmuxtui_capture $TARGET_A 3")
+  [ "$out" = $'hist two\nscreen one\nscreen two' ] \
+    || fail "capture should prepend right-trimmed history rows before the screen, got '$out'"
+  pass "fm_backend_cmuxtui_capture: appends contiguous scrollback for a larger-than-viewport request"
+}
+
+test_capture_fails_when_target_not_ready() {
+  local dir fb status
+  dir="$TMP_ROOT/capture-not-ready"; mkdir -p "$dir/responses"
+  cmuxtui_typed_error_response "$dir" 1 selector.not_found false 1
+  fb=$(make_cmuxtui_fakebin "$dir")
+  run_adapter "$dir" "$fb" "fm_backend_cmuxtui_capture $TARGET_A 5"
+  status=$?
+  [ "$status" -ne 0 ] || fail "capture should fail when the target terminal is absent"
+  assert_not_contains "$(cat "$dir/log")" $'\x1f''screen'$'\x1f''read' \
+    "capture should not read after readiness fails"
+  pass "fm_backend_cmuxtui_capture: fails when the target terminal is absent"
+}
+
+test_send_literal_does_not_submit() {
+  local dir fb log
+  dir="$TMP_ROOT/sendliteral"; mkdir -p "$dir/responses"
+  cmuxtui_terminal_show_response "$dir" 1 "$TERM_A"
+  fb=$(make_cmuxtui_fakebin "$dir")
+  run_adapter "$dir" "$fb" "fm_backend_cmuxtui_send_literal $TARGET_A '--help'" \
+    || fail "send_literal should succeed"
+  log=$(cat "$dir/log")
+  assert_contains "$log" $'\x1f''terminal'$'\x1f'"$TERM_A"$'\x1f''write'$'\x1f''--text'$'\x1f''--help' \
+    "send_literal did not pass the text through write --text"
+  assert_not_contains "$log" $'\x1f''keys' "send_literal must never submit"
+  pass "fm_backend_cmuxtui_send_literal: writes unsubmitted text, option-shaped payloads included"
+}
+
+test_send_key_normalizes_and_targets() {
+  local dir fb
+  dir="$TMP_ROOT/sendkey"; mkdir -p "$dir/responses"
+  cmuxtui_terminal_show_response "$dir" 1 "$TERM_A"
+  fb=$(make_cmuxtui_fakebin "$dir")
+  run_adapter "$dir" "$fb" "fm_backend_cmuxtui_send_key $TARGET_A Escape" \
+    || fail "send_key should succeed"
+  assert_contains "$(cat "$dir/log")" $'\x1f''terminal'$'\x1f'"$TERM_A"$'\x1f''keys'$'\x1f''escape' \
+    "send_key did not normalize Escape to escape against the explicit terminal"
+  pass "fm_backend_cmuxtui_send_key: normalizes the key and targets the explicit terminal id"
+}
+
+test_send_text_line_clears_partial_input_when_enter_fails() {
+  local dir fb status log
+  dir="$TMP_ROOT/sendline-enter-failure"; mkdir -p "$dir/responses"
+  # 1: terminal show (literal), 2: write, 3: terminal show (Enter), 4: keys enter FAILS,
+  # 5: terminal show (C-c cleanup), 6: keys ctrl+c
+  cmuxtui_terminal_show_response "$dir" 1 "$TERM_A"
+  cmuxtui_terminal_show_response "$dir" 3 "$TERM_A"
+  cmuxtui_typed_error_response "$dir" 4 mutation.indeterminate false 1
+  cmuxtui_terminal_show_response "$dir" 5 "$TERM_A"
+  fb=$(make_cmuxtui_fakebin "$dir")
+  run_adapter "$dir" "$fb" "fm_backend_cmuxtui_send_text_line $TARGET_A 'export TRACEPARENT=carrier'"
+  status=$?
+  [ "$status" -ne 0 ] || fail "send_text_line should report a failed Enter"
+  log=$(cat "$dir/log")
+  assert_contains "$log" $'\x1f''keys'$'\x1f''ctrl+c' \
+    "send_text_line did not clear the partial input after Enter failed"
+  pass "fm_backend_cmuxtui_send_text_line: clears partial input when Enter fails"
+}
+
+test_send_text_line_reports_unsafe_input_when_cleanup_fails() {
+  local dir fb status
+  dir="$TMP_ROOT/sendline-cleanup-failure"; mkdir -p "$dir/responses"
+  cmuxtui_terminal_show_response "$dir" 1 "$TERM_A"
+  cmuxtui_terminal_show_response "$dir" 3 "$TERM_A"
+  cmuxtui_typed_error_response "$dir" 4 mutation.indeterminate false 1
+  cmuxtui_terminal_show_response "$dir" 5 "$TERM_A"
+  cmuxtui_typed_error_response "$dir" 6 mutation.indeterminate false 1
+  fb=$(make_cmuxtui_fakebin "$dir")
+  run_adapter "$dir" "$fb" "fm_backend_cmuxtui_send_text_line $TARGET_A 'export TRACEPARENT=carrier'"
+  status=$?
+  expect_code 2 "$status" "send_text_line should distinguish uncleared input"
+  pass "fm_backend_cmuxtui_send_text_line: reports unsafe input when cleanup also fails"
+}
+
+# --- composer_state: cursor-anchored shared classification --------------------
+
+test_composer_state_bare_prompt_is_empty() {
+  local dir fb out
+  dir="$TMP_ROOT/composer-bare"; mkdir -p "$dir/responses"
+  cmuxtui_terminal_show_response "$dir" 1 "$TERM_A"
+  cmuxtui_screen_read_response "$dir" 2 $'transcript line\n❯' 1
+  fb=$(make_cmuxtui_fakebin "$dir")
+  out=$(run_adapter "$dir" "$fb" "fm_backend_cmuxtui_composer_state $TARGET_A")
+  [ "$out" = empty ] || fail "a bare '❯' row under the cursor should read empty, got '$out'"
+  pass "fm_backend_cmuxtui_composer_state: a bare '❯' row under the cursor reads empty"
+}
+
+test_composer_state_bordered_text_is_pending() {
+  local dir fb out
+  dir="$TMP_ROOT/composer-pending"; mkdir -p "$dir/responses"
+  cmuxtui_terminal_show_response "$dir" 1 "$TERM_A"
+  cmuxtui_screen_read_response "$dir" 2 $'  ╭────────────────────────╮\n  │ ❯ hello captain        │\n  ╰──────── Composer ──────╯\n\n  Enter:send' 1
+  fb=$(make_cmuxtui_fakebin "$dir")
+  out=$(run_adapter "$dir" "$fb" "fm_backend_cmuxtui_composer_state $TARGET_A")
+  [ "$out" = pending ] || fail "real bordered composer text should read pending, got '$out'"
+  pass "fm_backend_cmuxtui_composer_state: cursor-anchored bordered text reads pending"
+}
+
+test_composer_state_bare_glyph_text_degrades_unknown() {
+  # styled=0: plain capture cannot tell typed input from the harness's own
+  # idle suggestion after a bare glyph, so the shared classifier degrades to
+  # unknown, never a false pending.
+  local dir fb out
+  dir="$TMP_ROOT/composer-unknown"; mkdir -p "$dir/responses"
+  cmuxtui_terminal_show_response "$dir" 1 "$TERM_A"
+  cmuxtui_screen_read_response "$dir" 2 $'transcript line\n❯ retain this message' 1
+  fb=$(make_cmuxtui_fakebin "$dir")
+  out=$(run_adapter "$dir" "$fb" "fm_backend_cmuxtui_composer_state $TARGET_A")
+  [ "$out" = unknown ] || fail "plain-capture text after a bare glyph must degrade to unknown, got '$out'"
+  pass "fm_backend_cmuxtui_composer_state: plain-capture bare-glyph text degrades to unknown"
+}
+
+test_composer_state_blank_cursor_row_is_unknown() {
+  local dir fb out
+  dir="$TMP_ROOT/composer-blank-row"; mkdir -p "$dir/responses"
+  cmuxtui_terminal_show_response "$dir" 1 "$TERM_A"
+  cmuxtui_screen_read_response "$dir" 2 $'transcript line\n\nplain-shell$ output' 1
+  fb=$(make_cmuxtui_fakebin "$dir")
+  out=$(run_adapter "$dir" "$fb" "fm_backend_cmuxtui_composer_state $TARGET_A")
+  [ "$out" = unknown ] || fail "a blank cursor row with no container proof must stay unknown, got '$out'"
+  pass "fm_backend_cmuxtui_composer_state: the strict blank-row rule holds under the cursor"
+}
+
+test_composer_state_hidden_cursor_falls_back_cursorless() {
+  local dir fb out
+  dir="$TMP_ROOT/composer-hidden-cursor"; mkdir -p "$dir/responses"
+  cmuxtui_terminal_show_response "$dir" 1 "$TERM_A"
+  # cursor_visible=false with a stale cursor_row pointing at the transcript;
+  # the bottom-most shape (the bare glyph) must still win.
+  cmuxtui_screen_read_response "$dir" 2 $'transcript line\n❯' 0 false
+  fb=$(make_cmuxtui_fakebin "$dir")
+  out=$(run_adapter "$dir" "$fb" "fm_backend_cmuxtui_composer_state $TARGET_A")
+  [ "$out" = empty ] || fail "a hidden cursor should fall back to cursorless bottom-most selection, got '$out'"
+  pass "fm_backend_cmuxtui_composer_state: a hidden cursor drops the cursor fact instead of anchoring stale"
+}
+
+test_composer_state_unknown_on_capture_failure() {
+  local dir fb out status
+  dir="$TMP_ROOT/composer-capture-fail"; mkdir -p "$dir/responses"
+  cmuxtui_typed_error_response "$dir" 1 selector.not_found false 1
+  fb=$(make_cmuxtui_fakebin "$dir")
+  out=$(run_adapter "$dir" "$fb" "fm_backend_cmuxtui_composer_state $TARGET_A")
+  status=$?
+  [ "$status" -eq 0 ] || fail "composer_state should not itself fail the caller"
+  [ "$out" = unknown ] || fail "an unreadable terminal should read as unknown, got '$out'"
+  pass "fm_backend_cmuxtui_composer_state: reports unknown when the terminal cannot be captured"
+}
+
+# --- send_text_submit: shared verify-and-retry-Enter --------------------------
+
+test_send_text_submit_detects_landed_send() {
+  local dir fb out enter_count
+  dir="$TMP_ROOT/submit-ok"; mkdir -p "$dir/responses"
+  # 1: terminal show (literal), 2: write, 3: terminal show (Enter), 4: keys enter,
+  # 5: terminal show (composer capture), 6: screen read -> empty composer
+  cmuxtui_terminal_show_response "$dir" 1 "$TERM_A"
+  cmuxtui_terminal_show_response "$dir" 3 "$TERM_A"
+  cmuxtui_terminal_show_response "$dir" 5 "$TERM_A"
+  cmuxtui_screen_read_response "$dir" 6 $'transcript line\n❯' 1
+  fb=$(make_cmuxtui_fakebin "$dir")
+  out=$(run_adapter "$dir" "$fb" "fm_backend_cmuxtui_send_text_submit $TARGET_A 'hello captain' 3 0.01 0.01")
+  [ "$out" = empty ] || fail "send_text_submit should report empty once the composer clears, got '$out'"
+  enter_count=$(grep -c $'\x1f''keys'$'\x1f''enter' "$dir/log")
+  [ "$enter_count" -eq 1 ] || fail "a landed plain send needs exactly one Enter, sent $enter_count"
+  pass "fm_backend_cmuxtui_send_text_submit: reports 'empty' once the composer reads empty after one Enter"
+}
+
+test_send_text_submit_detects_swallowed_enter() {
+  local dir fb out
+  dir="$TMP_ROOT/submit-swallow"; mkdir -p "$dir/responses"
+  cmuxtui_terminal_show_response "$dir" 1 "$TERM_A"
+  cmuxtui_terminal_show_response "$dir" 3 "$TERM_A"
+  cmuxtui_terminal_show_response "$dir" 5 "$TERM_A"
+  cmuxtui_screen_read_response "$dir" 6 $'  ╭───────────────────╮\n  │ ❯ hello captain   │\n  ╰───────────────────╯' 1
+  cmuxtui_terminal_show_response "$dir" 7 "$TERM_A"
+  cmuxtui_terminal_show_response "$dir" 9 "$TERM_A"
+  cmuxtui_screen_read_response "$dir" 10 $'  ╭───────────────────╮\n  │ ❯ hello captain   │\n  ╰───────────────────╯' 1
+  fb=$(make_cmuxtui_fakebin "$dir")
+  out=$(run_adapter "$dir" "$fb" "fm_backend_cmuxtui_send_text_submit $TARGET_A 'hello captain' 2 0.01 0.01")
+  [ "$out" = pending ] || fail "send_text_submit should report pending after exhausted Enter retries, got '$out'"
+  assert_not_contains "$(cat "$dir/log")" $'\x1f''write'$'\x1f''--text'$'\x1f''hello captain'$'\x1f''--text' \
+    "send_text_submit must never retype"
+  [ "$(grep -c $'\x1f''write' "$dir/log")" = 1 ] || fail "the text must be typed exactly once"
+  pass "fm_backend_cmuxtui_send_text_submit: reports 'pending' on a swallowed Enter and never retypes"
+}
+
+test_send_text_submit_send_failed_when_target_absent() {
+  local dir fb out
+  dir="$TMP_ROOT/submit-no-target"; mkdir -p "$dir/responses"
+  cmuxtui_typed_error_response "$dir" 1 selector.not_found false 1
+  fb=$(make_cmuxtui_fakebin "$dir")
+  out=$(run_adapter "$dir" "$fb" "fm_backend_cmuxtui_send_text_submit $TARGET_A x 2 0.01 0.01")
+  [ "$out" = send-failed ] || fail "send_text_submit should report send-failed when the target is absent, got '$out'"
+  pass "fm_backend_cmuxtui_send_text_submit: reports 'send-failed' when the target terminal is absent"
+}
+
+# --- current_path: structured cwd, child-pid subshell fallback ----------------
+
+test_current_path_prefers_child_pid_cwd() {
+  local dir fb out
+  dir="$TMP_ROOT/cwd-child"; mkdir -p "$dir/responses"
+  cmuxtui_terminal_show_response "$dir" 1 "$TERM_A"
+  printf '{"argv":["/bin/zsh"],"children":[4242],"cwd":"file://somehost/frozen/launch/dir","executable":"/bin/zsh","pid":100}' \
+    > "$dir/responses/2.out"
+  fb=$(make_cmuxtui_fakebin "$dir")
+  # Fake lsof: the macOS child-pid cwd read (this suite runs where /proc is absent).
+  cat > "$fb/lsof" <<'SH'
+#!/usr/bin/env bash
+printf 'p4242\nfcwd\nn/live/subshell/worktree\n'
+SH
+  chmod +x "$fb/lsof"
+  out=$(run_adapter "$dir" "$fb" "fm_backend_cmuxtui_current_path $TARGET_A")
+  [ "$out" = /live/subshell/worktree ] \
+    || fail "current_path should prefer the foreground child pid's OS-level cwd, got '$out'"
+  pass "fm_backend_cmuxtui_current_path: a foreground subshell's cwd comes from the child pid, not the frozen field"
+}
+
+test_current_path_falls_back_to_structured_cwd() {
+  local dir fb out
+  dir="$TMP_ROOT/cwd-top"; mkdir -p "$dir/responses"
+  cmuxtui_terminal_show_response "$dir" 1 "$TERM_A"
+  printf '{"argv":["/bin/zsh"],"children":[],"cwd":"file://somehost/private/tmp/proj","executable":"/bin/zsh","pid":100}' \
+    > "$dir/responses/2.out"
+  fb=$(make_cmuxtui_fakebin "$dir")
+  out=$(run_adapter "$dir" "$fb" "fm_backend_cmuxtui_current_path $TARGET_A")
+  [ "$out" = /private/tmp/proj ] \
+    || fail "current_path should strip the file://<host> prefix from the structured cwd, got '$out'"
+  pass "fm_backend_cmuxtui_current_path: a childless shell uses the structured cwd with scheme and host stripped"
+}
+
+test_current_path_empty_when_target_gone() {
+  local dir fb out
+  dir="$TMP_ROOT/cwd-gone"; mkdir -p "$dir/responses"
+  cmuxtui_typed_error_response "$dir" 1 selector.not_found false 1
+  fb=$(make_cmuxtui_fakebin "$dir")
+  out=$(run_adapter "$dir" "$fb" "fm_backend_cmuxtui_current_path $TARGET_A")
+  [ -z "$out" ] || fail "current_path should print nothing for a dead target, got '$out'"
+  pass "fm_backend_cmuxtui_current_path: prints nothing (never fails) for a dead target"
+}
+
+# --- busy_state: native hook-fed agent record ---------------------------------
+
+test_busy_state_maps_agent_states() {
+  local dir fb out state expected
+  for state in working idle 'done' blocked; do
+    case "$state" in
+      working) expected=busy ;;
+      *) expected=idle ;;
+    esac
+    dir="$TMP_ROOT/busy-$state"; mkdir -p "$dir/responses"
+    cmuxtui_agent_list_response "$dir" 1 "$TERM_A" "$state" 1000
+    fb=$(make_cmuxtui_fakebin "$dir")
+    out=$(run_adapter "$dir" "$fb" "fm_backend_cmuxtui_busy_state $TARGET_A")
+    [ "$out" = "$expected" ] || fail "agent state '$state' should map to '$expected', got '$out'"
+  done
+  pass "fm_backend_cmuxtui_busy_state: working->busy, idle/done/blocked->idle (herdr's mapping)"
+}
+
+test_busy_state_unknown_without_agent_row() {
+  local dir fb out
+  dir="$TMP_ROOT/busy-none"; mkdir -p "$dir/responses"
+  printf '[]' > "$dir/responses/1.out"
+  fb=$(make_cmuxtui_fakebin "$dir")
+  out=$(run_adapter "$dir" "$fb" "fm_backend_cmuxtui_busy_state $TARGET_A")
+  [ "$out" = unknown ] || fail "no agent row should read unknown, got '$out'"
+  pass "fm_backend_cmuxtui_busy_state: no hook-fed row reads unknown (pane-regex fallback cue)"
+}
+
+test_busy_state_newest_row_wins() {
+  local dir fb out
+  dir="$TMP_ROOT/busy-newest"; mkdir -p "$dir/responses"
+  jq -n --arg t "$TERM_A" '[
+    {id:"agent_1", terminal_id:$t, state:"working", source:"hook", updated_at_ms:"1000"},
+    {id:"agent_2", terminal_id:$t, state:"idle", source:"hook", updated_at_ms:"2000"}
+  ]' > "$dir/responses/1.out"
+  fb=$(make_cmuxtui_fakebin "$dir")
+  out=$(run_adapter "$dir" "$fb" "fm_backend_cmuxtui_busy_state $TARGET_A")
+  [ "$out" = idle ] || fail "the newest agent row should win, got '$out'"
+  pass "fm_backend_cmuxtui_busy_state: the newest updated_at_ms row wins"
+}
+
+# --- kill / list_live ----------------------------------------------------------
+
+test_kill_closes_workspace() {
+  local dir fb
+  dir="$TMP_ROOT/kill"; mkdir -p "$dir/responses"
+  fb=$(make_cmuxtui_fakebin "$dir")
+  run_adapter "$dir" "$fb" "fm_backend_cmuxtui_kill $TARGET_A" \
+    || fail "kill must stay best-effort"
+  assert_contains "$(cat "$dir/log")" $'\x1f''workspace'$'\x1f'"$WS_A"$'\x1f''close' \
+    "kill did not close the task workspace"
+  pass "fm_backend_cmuxtui_kill: closes the task's whole workspace"
+}
+
+test_kill_is_best_effort_when_close_fails() {
+  local dir fb
+  dir="$TMP_ROOT/kill-fail"; mkdir -p "$dir/responses"
+  cmuxtui_typed_error_response "$dir" 1 selector.not_found false 1
+  fb=$(make_cmuxtui_fakebin "$dir")
+  run_adapter "$dir" "$fb" "fm_backend_cmuxtui_kill $TARGET_A" \
+    || fail "kill must never fail, even when close-workspace fails"
+  pass "fm_backend_cmuxtui_kill: never fails even when the close fails"
+}
+
+test_kill_recovers_stale_target_by_label() {
+  local dir fb log
+  dir="$TMP_ROOT/kill-stale"; mkdir -p "$dir/responses"
+  # target_ready label recovery: 1 workspace show (stale id gone), 2 workspace
+  # list (unambiguous label), 3 snapshot (terminal), then 4 close on the
+  # REFRESHED workspace id.
+  cmuxtui_typed_error_response "$dir" 1 selector.not_found false 1
+  cmuxtui_workspace_list_response "$dir" 2 "$WS_B" fm-label
+  cmuxtui_snapshot_response "$dir" 3 "$WS_B" fm-label tab_1 "$TERM_B"
+  fb=$(make_cmuxtui_fakebin "$dir")
+  run_adapter "$dir" "$fb" "fm_backend_cmuxtui_kill $TARGET_A '' fm-label" \
+    || fail "kill should recover a stale target when the expected label is live"
+  log=$(cat "$dir/log")
+  assert_contains "$log" $'\x1f''workspace'$'\x1f'"$WS_B"$'\x1f''close' \
+    "kill did not close the refreshed workspace id"
+  assert_not_contains "$log" $'\x1f''workspace'$'\x1f'"$WS_A"$'\x1f''close' \
+    "kill must not close the stale workspace id after label recovery"
+  pass "fm_backend_cmuxtui_kill: recovers a stale workspace id through the guarded label path"
+}
+
+test_list_live_filters_fm_workspaces() {
+  local dir fb out
+  dir="$TMP_ROOT/list-live"; mkdir -p "$dir/responses"
+  jq -n --arg ws "$WS_A" --arg term "$TERM_A" '{
+    workspaces: [
+      {id:$ws, name:"fm-task1", focused:false, index:0},
+      {id:"ws_dddddddddddddddddddddddddddddddd", name:"scratch", focused:true, index:1}
+    ],
+    screens: [
+      {id:"screen_1", workspace_id:$ws, layout:{root:{kind:"leaf", tab_ids:["tab_1"]}}},
+      {id:"screen_2", workspace_id:"ws_dddddddddddddddddddddddddddddddd", layout:{root:{kind:"leaf", tab_ids:["tab_2"]}}}
+    ],
+    tabs: [
+      {id:"tab_1", content_kind:"terminal", content_id:$term},
+      {id:"tab_2", content_kind:"terminal", content_id:"term_33333333333333333333333333333333"}
+    ]
+  }' > "$dir/responses/1.out"
+  fb=$(make_cmuxtui_fakebin "$dir")
+  out=$(run_adapter "$dir" "$fb" 'fm_backend_cmuxtui_list_live')
+  [ "$out" = "$WS_A:$TERM_A"$'\t''fm-task1' ] \
+    || fail "list_live should list only fm- task workspaces with their terminal ids, got '$out'"
+  pass "fm_backend_cmuxtui_list_live: lists only fm- task workspaces from one snapshot read"
+}
+
+# --- fm-spawn.sh: --secondmate refuses backend=cmux-tui -----------------------
+
+test_secondmate_spawn_refuses_cmuxtui_backend() {
+  local dir state data config projects out status
+  dir="$TMP_ROOT/secondmate-refuse"; state="$dir/state"; data="$dir/data"; config="$dir/config"; projects="$dir/projects"
+  mkdir -p "$state" "$data" "$config" "$projects"
+  out=$( FM_STATE_OVERRIDE="$state" FM_DATA_OVERRIDE="$data" FM_CONFIG_OVERRIDE="$config" FM_PROJECTS_OVERRIDE="$projects" \
+    "$ROOT/bin/fm-spawn.sh" sm-cmuxtui-test --secondmate --backend cmux-tui 2>&1 )
+  status=$?
+  [ "$status" -ne 0 ] || fail "fm-spawn.sh should refuse a --secondmate spawn with --backend cmux-tui"
+  assert_contains "$out" "does not support --secondmate" "fm-spawn.sh did not report the cmux-tui secondmate refusal"
+  pass "fm-spawn.sh: refuses backend=cmux-tui for --secondmate spawns (no secondmate launch design yet)"
+}
+
+# shellcheck source=/dev/null
+. "$ROOT/bin/fm-backend.sh"
+
+test_version_check_accepts_current_version
+test_version_check_accepts_newer_version
+test_version_check_refuses_old_version
+test_version_check_refuses_missing_binary
+test_bin_honors_override
+test_session_name_is_home_scoped
+test_session_name_override
+test_cli_exports_adapter_owned_config
+test_parse_target
+test_normalize_key
+test_dispatch_routes_cmuxtui_backend
+test_detect_cmuxtui_socket_marker
+test_detect_cmuxtui_legacy_marker
+test_detect_inner_multiplexers_win_over_cmuxtui
+test_detect_cmuxtui_wins_over_gui_cmux_marker
+test_backend_name_notices_autodetected_cmuxtui
+test_dispatch_busy_state_routes_cmuxtui
+test_endpoint_validation_accepts_and_refuses
+test_create_task_refuses_duplicate_label
+test_create_task_creates_and_parses_ids
+test_mutate_retries_indeterminate_with_same_key
+test_mutate_does_not_retry_terminal_errors
+test_target_ready_fails_when_terminal_absent
+test_target_ready_verifies_expected_label
+test_target_ready_rejects_label_mismatch
+test_target_ready_adopts_unambiguous_label_when_id_gone
+test_target_ready_refuses_ambiguous_label
+test_capture_trims_screen_locally
+test_capture_appends_history_for_large_requests
+test_capture_fails_when_target_not_ready
+test_send_literal_does_not_submit
+test_send_key_normalizes_and_targets
+test_send_text_line_clears_partial_input_when_enter_fails
+test_send_text_line_reports_unsafe_input_when_cleanup_fails
+test_composer_state_bare_prompt_is_empty
+test_composer_state_bordered_text_is_pending
+test_composer_state_bare_glyph_text_degrades_unknown
+test_composer_state_blank_cursor_row_is_unknown
+test_composer_state_hidden_cursor_falls_back_cursorless
+test_composer_state_unknown_on_capture_failure
+test_send_text_submit_detects_landed_send
+test_send_text_submit_detects_swallowed_enter
+test_send_text_submit_send_failed_when_target_absent
+test_current_path_prefers_child_pid_cwd
+test_current_path_falls_back_to_structured_cwd
+test_current_path_empty_when_target_gone
+test_busy_state_maps_agent_states
+test_busy_state_unknown_without_agent_row
+test_busy_state_newest_row_wins
+test_kill_closes_workspace
+test_kill_is_best_effort_when_close_fails
+test_kill_recovers_stale_target_by_label
+test_list_live_filters_fm_workspaces
+test_secondmate_spawn_refuses_cmuxtui_backend
diff --git a/tests/fm-backend.test.sh b/tests/fm-backend.test.sh
index ece981b1222..cf6cb6faa4f 100755
--- a/tests/fm-backend.test.sh
+++ b/tests/fm-backend.test.sh
@@ -38,6 +38,13 @@ fm_git_identity fmtest fmtest@example.invalid
 
 TMP_ROOT=$(fm_test_tmproot fm-backend-tests)
 
+# The cmux-tui runtime markers would flip every detection assertion below
+# when this suite itself runs inside a cmux-tui terminal, exactly like the
+# per-case TMUX/HERDR_ENV/CMUX_WORKSPACE_ID unsets. Nothing in this suite
+# consumes them, so one global unset keeps every case deterministic; the
+# cmux-tui detection cases themselves live in tests/fm-backend-cmux-tui.test.sh.
+unset CMUX_TUI_SOCKET CMUX_MUX_SOCKET
+
 # fm_backend_detect's cmux fallback (bundle id + process ancestry,
 # docs/cmux-backend.md "Runtime auto-detection") consults uname, lsappinfo,
 # and ps. FAKE_NONDARWIN_BIN pins uname to Linux so the whole fallback is

From d4911b8ae6bd869a27eee3ebab800f3b3bd5c30a Mon Sep 17 00:00:00 2001
From: lawrencecchen <54008264+lawrencecchen@users.noreply.github.com>
Date: Mon, 24 Aug 2026 23:38:10 -0700
Subject: [PATCH 3/3] docs(backend): cmux-tui operator guide, selection docs,
 and live evidence

docs/cmux-tui-backend.md is the operator guide: setup (binary on PATH or
FM_CMUXTUI_BIN, jq, no socket-access matrix), the one-session-per-home
shape, target and metadata shape, operational notes (literal-then-Enter,
cursor-aware composer capture, durable-id recovery, last-workspace close
allowed, correlation-key nonces), and the active limits that remain
(native name uniqueness unenforced, inherent TOCTOU, scrubbable env
markers, child-pid subshell cwd until a native foreground-cwd field,
hook-fed agent state, no push wait yet).

docs/verification/runtime-backends.md gains the dated cmux-tui section
with the exact commands and observed output behind each guarantee,
including the durable-id restart proof, the frozen-subshell cwd
counterexample, and the replay-after-close correlation-key hazard.

configuration.md's runtime-backend section, the FM_* environment listing,
AGENTS.md's config/backend line, cmux-backend.md's disambiguation pointer,
and the documentation-audiences inventory all pick up the new backend.
---
 AGENTS.md                             |  2 +-
 docs/cmux-backend.md                  |  1 +
 docs/cmux-tui-backend.md              | 88 +++++++++++++++++++++++++++
 docs/configuration.md                 | 23 ++++---
 docs/documentation-audiences.json     |  8 +++
 docs/verification/runtime-backends.md | 43 +++++++++++++
 6 files changed, 156 insertions(+), 9 deletions(-)
 create mode 100644 docs/cmux-tui-backend.md

diff --git a/AGENTS.md b/AGENTS.md
index faa516ef620..705f4c1d2d7 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -68,7 +68,7 @@ config/crew-harness  crewmate harness override; LOCAL, gitignored; absent or "de
 config/crew-dispatch.json  optional crewmate dispatch profiles; LOCAL, gitignored; firstmate-maintained but human-editable natural-language rules that choose a per-task harness/model/effort profile (section 4). Inherited by secondmate homes
 config/secondmate-harness  harness the PRIMARY uses to launch SECONDMATE agents, optionally followed by a model and effort token on the same line ("<harness> [<model>] [<effort>]"; section 4); LOCAL, gitignored; absent or "default" harness falls back to config/crew-harness then firstmate's own. The primary's own setting; NOT inherited into secondmate homes (secondmates do not spawn secondmates)
 config/backlog-backend  backlog backend override; LOCAL, gitignored; absent or "tasks-axi" = default tasks-axi backend, "manual" = force routine backlog updates to hand-editing; inherited by secondmate homes (section 10)
-config/backend  runtime session-provider backend override for new tasks; LOCAL, gitignored; absent = falls through to runtime auto-detection (the runtime firstmate itself is executing inside), then tmux; tmux is the verified reference backend (docs/tmux-backend.md), while herdr, zellij, orca, and cmux are experimental spawn backends (docs/herdr-backend.md, docs/zellij-backend.md, docs/orca-backend.md, docs/cmux-backend.md) - herdr and cmux can also be selected by runtime auto-detection, zellij and orca never are (always explicit), and codex-app is not accepted; see docs/codex-app-backend.md; inherited by secondmate homes under the primary-authoritative contract in secondmate-provisioning
+config/backend  runtime session-provider backend override for new tasks; LOCAL, gitignored; absent = falls through to runtime auto-detection (the runtime firstmate itself is executing inside), then tmux; tmux is the verified reference backend (docs/tmux-backend.md), while herdr, zellij, orca, cmux, and cmux-tui are experimental spawn backends (docs/herdr-backend.md, docs/zellij-backend.md, docs/orca-backend.md, docs/cmux-backend.md, docs/cmux-tui-backend.md) - herdr, cmux, and cmux-tui can also be selected by runtime auto-detection, zellij and orca never are (always explicit), and codex-app is not accepted; see docs/codex-app-backend.md; inherited by secondmate homes under the primary-authoritative contract in secondmate-provisioning
 config/calm     Pi Calm presentation preference; LOCAL, gitignored, and not inherited; see docs/configuration.md "Pi Calm preference"
 config/startup-memory-budget     primary-authoritative per-home startup-memory budget; LOCAL, gitignored, materialized as 7,500 estimated tokens by locked primary bootstrap and inherited into secondmate homes; see docs/configuration.md "Startup memory budget"
 config/stow-pass-horizon  optional presence flag opting this home in to /stow's default-off pass-count decay horizon; LOCAL, gitignored, and not inherited; see docs/configuration.md "Stow pass horizon"
diff --git a/docs/cmux-backend.md b/docs/cmux-backend.md
index 51618de5b5f..42e49a5fb84 100644
--- a/docs/cmux-backend.md
+++ b/docs/cmux-backend.md
@@ -1,6 +1,7 @@
 # cmux runtime backend
 
 cmux is an experimental macOS GUI terminal backend.
+The headless Rust multiplexer from the same repository is a separate backend; see [`cmux-tui-backend.md`](cmux-tui-backend.md).
 It provides task workspaces and surfaces while Treehouse continues to provide git worktrees.
 [`configuration.md`](configuration.md#runtime-backend-configbackend--fm_backend) owns shared selection and metadata semantics.
 
diff --git a/docs/cmux-tui-backend.md b/docs/cmux-tui-backend.md
new file mode 100644
index 00000000000..f12ea523f3e
--- /dev/null
+++ b/docs/cmux-tui-backend.md
@@ -0,0 +1,88 @@
+# cmux-tui runtime backend
+
+cmux-tui is an experimental headless terminal-multiplexer backend, the Rust `cmux-tui` binary from [manaflow-ai/cmux](https://github.com/manaflow-ai/cmux).
+It is a different product from the macOS GUI app that the [`cmux` backend](cmux-backend.md) drives, and the two backends are independent.
+It provides task workspaces and terminals while Treehouse continues to provide git worktrees.
+[`configuration.md`](configuration.md#runtime-backend-configbackend--fm_backend) owns shared selection and metadata semantics.
+
+## Setup
+
+Pick cmux-tui when crews should run headless with no GUI app, including on Linux and over SSH.
+
+Prerequisites:
+
+- The `cmux-tui` binary (0.1 or newer) on `PATH`, or `FM_CMUXTUI_BIN` pointing at it.
+- `jq` for JSON responses.
+- The universal harness and toolchain requirements in [`configuration.md`](configuration.md#toolchain).
+
+There is no socket-access matrix and no password: the session socket lives in a 0700 per-uid directory and admits the same user by default.
+
+Select cmux-tui with local `config/backend` containing `cmux-tui`, `FM_BACKEND=cmux-tui` for one launch, or an explicit request to Firstmate.
+It is also runtime auto-detected when Firstmate itself runs inside a cmux-tui terminal, from the injected `CMUX_TUI_SOCKET` marker (or its legacy `CMUX_MUX_SOCKET` alias).
+Detection checks tmux first, then Herdr, then cmux-tui, then the cmux GUI app: an inner multiplexer always wins, and a cmux-tui session started inside a cmux GUI tab still resolves to cmux-tui because the GUI marker is inherited from outside.
+A spawn stops with an actionable setup message when the binary, minimum version, or `jq` is unavailable.
+
+Every adapter invocation exports `CMUX_TUI_CONFIG` pointing at an adapter-owned config file (default `state/cmux-tui/cmux-tui.json`, created as `{}`).
+This is load-bearing: an operator's own `~/.config/cmux/cmux-tui.json` may configure a machine provider that refuses `--session`/`--headless` startup outright.
+`FM_CMUXTUI_CONFIG` overrides the file for test isolation.
+
+## Task shape and metadata
+
+Each firstmate home owns one dedicated headless session named `fm-<home-label>` (`FM_CMUXTUI_SESSION` overrides for tests), started with `server start --session <name> --headless --state <dir>` against the adapter-owned state dir `state/cmux-tui` (`FM_CMUXTUI_STATE` overrides).
+The adapter never touches the operator's own sessions, including the default `main` session, because every CLI call carries the home session's explicit `--session` flag.
+Each task owns one workspace with one terminal tab inside that session.
+Because the session itself is home-scoped, workspace names are the plain caller-facing `fm-<id>` labels with no home tag.
+cmux-tui does not enforce workspace-name uniqueness, so the create path refuses a live duplicate label itself, and that check-then-create window is an inherent TOCTOU.
+
+```text
+backend=cmux-tui
+window=<workspace-id>:<terminal-id>
+cmuxtui_session=<session-name>
+cmuxtui_workspace_id=<workspace-id>
+cmuxtui_terminal_id=<terminal-id>
+```
+
+Workspace and terminal ids are durable across server restarts (verified live: the same `ws_`/`term_` ids come back from the same `--state` dir).
+The recorded id pair is therefore the recovery authority.
+Names are display labels only: a stale id is re-resolved by label solely through the standard exactly-one duplicate guard, and an ambiguous name refuses rather than guessing.
+
+## Current operation and safety
+
+Literal send and Enter are separate calls: `terminal <id> write --text` never auto-submits, and `terminal <id> keys <chord>` delivers Enter, Escape, Ctrl-C, Ctrl-D, Ctrl-U, Tab, Up, and Down (lowercase chords, invalid chords return a typed error).
+`screen read` works on a genuinely fresh terminal and returns the live cursor position, so the composer verifier hands the shared classifier in `bin/fm-composer-lib.sh` a cursor-anchored capture (`cursor=1`).
+The capture is plain text (`styled=0`), so ghost text stays unreadable and a bare glyph row carrying trailing text still degrades to `unknown` rather than a false `pending`.
+A hidden cursor drops the cursor fact for that read instead of anchoring on a stale row.
+Captures larger than the viewport append the terminal's retained scrollback from `history read`, which is contiguous with the visible screen.
+
+Worktree-path discovery is structured, never screen-scraped: `process show --json` reports the top-level shell's live cwd (a `file://<host>/path` URL, scheme and host stripped) plus child pids.
+That structured cwd freezes when an integration-free foreground subshell (the `treehouse get` case) changes directory, so child pids are consulted first through their OS-level cwd (`lsof -a -p <pid> -d cwd -Fn` on macOS, `/proc/<pid>/cwd` on Linux).
+`terminal <id> screen wait --pattern <regex> --timeout-ms <n>` exists as an event-driven output wait for future use.
+
+Mutations go through a wrapper that attaches a per-attempt `--correlation-key` nonce and retries once with the same key on a retryable or `mutation.indeterminate` typed error.
+Keys are never derived from stable labels: a replayed key returns the original attempt's result even after that workspace was closed (verified live), so a label-derived key would resurrect stale ids.
+
+Native per-terminal agent state exists: `agent list --json` rows carry `working|blocked|idle|done|unknown`, hook-fed via `agent report` and `agent hook install`.
+`fm_backend_busy_state` maps them exactly as Herdr's agent status is mapped: `working` is busy, `idle`/`done`/`blocked` are idle, and no row is unknown, the watcher's cue to fall back to pane-regex detection.
+
+Cleanup closes the task's whole workspace.
+Closing the last workspace of the session works natively, and the session server keeps running with an empty tree, so there is no sibling-workspace dance and no ghost tab.
+Real tests spin up their own isolated throwaway session (`FM_CMUXTUI_SESSION=fm-tui-test-*`) with `fm-test-` labels and a scratch `--state` dir, stop that session afterward, and never enumerate-and-close anything in a shared namespace.
+
+## Active limits
+
+- cmux-tui is experimental, and secondmate spawns are unsupported until a per-home lifecycle design is verified.
+- Workspace-name uniqueness is not enforced natively, so the duplicate refusal is the adapter's own and its check-then-create window is inherent.
+- Env markers are ordinary environment variables a wrapper can scrub, like every other backend's markers.
+- A target can disappear between a structural readiness read and the operation.
+- A foreground subshell's cwd needs the child-pid lookup until cmux-tui ships a native foreground-cwd field.
+- Agent state is hook-fed, so a harness without installed hooks reports no row and supervision falls back to screen polling.
+- There is no native push-event wait wired into the watcher yet; `screen wait` exists but `fm_backend_has_push` still reports false.
+
+## Regression entry points
+
+```sh
+tests/fm-backend-cmux-tui.test.sh
+tests/fm-backend-cmux-tui-smoke.test.sh
+```
+
+[`verification/runtime-backends.md`](verification/runtime-backends.md#cmux-tui) records the active live evidence, including durable-id restart proof and the frozen-subshell cwd counterexample.
diff --git a/docs/configuration.md b/docs/configuration.md
index 62a7db10610..f179ac4d6c5 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -63,15 +63,15 @@ The file format is unchanged in both modes; tasks-axi and manual edits produce t
 ## Runtime backend (config/backend / FM_BACKEND)
 
 For spawn-capable adapters, the runtime session-provider backend controls where task windows/endpoints are created, captured, sent to, watched, and killed.
-`tmux` is the verified reference backend (see [`docs/tmux-backend.md`](tmux-backend.md)); `herdr`, `zellij`, `orca`, and `cmux` are experimental spawn backends (see [`docs/herdr-backend.md`](herdr-backend.md), [`docs/zellij-backend.md`](zellij-backend.md), [`docs/orca-backend.md`](orca-backend.md), and [`docs/cmux-backend.md`](cmux-backend.md)).
-Treehouse remains the worktree provider for tmux, herdr, zellij, and cmux, since herdr, zellij, and cmux are session providers only; Orca provides both the task worktree and terminal endpoint.
-New spawns choose the backend in this order: an explicit `--backend` flag that current authority for that exact task alone has authorized (a present captain instruction or the task's own accepted brief; never later-task precedent by analogy), then `FM_BACKEND`, then the first non-empty line of local gitignored `config/backend`, then runtime auto-detection from `$TMUX`, `HERDR_ENV=1`, or cmux runtime signals, then default `tmux`.
-If more than one runtime marker is present, detection resolves innermost-first: `$TMUX` is checked before `HERDR_ENV=1`, which is checked before cmux's primary `CMUX_WORKSPACE_ID` marker and its documented fallback signals - tmux or herdr started from inside a cmux terminal is the innermost, currently-executing layer, while cmux itself (a terminal application, not a nestable multiplexer) is always checked last.
+`tmux` is the verified reference backend (see [`docs/tmux-backend.md`](tmux-backend.md)); `herdr`, `zellij`, `orca`, `cmux`, and `cmux-tui` are experimental spawn backends (see [`docs/herdr-backend.md`](herdr-backend.md), [`docs/zellij-backend.md`](zellij-backend.md), [`docs/orca-backend.md`](orca-backend.md), [`docs/cmux-backend.md`](cmux-backend.md), and [`docs/cmux-tui-backend.md`](cmux-tui-backend.md)).
+Treehouse remains the worktree provider for tmux, herdr, zellij, cmux, and cmux-tui, since herdr, zellij, cmux, and cmux-tui are session providers only; Orca provides both the task worktree and terminal endpoint.
+New spawns choose the backend in this order: an explicit `--backend` flag that current authority for that exact task alone has authorized (a present captain instruction or the task's own accepted brief; never later-task precedent by analogy), then `FM_BACKEND`, then the first non-empty line of local gitignored `config/backend`, then runtime auto-detection from `$TMUX`, `HERDR_ENV=1`, cmux-tui's `CMUX_TUI_SOCKET`/`CMUX_MUX_SOCKET`, or cmux runtime signals, then default `tmux`.
+If more than one runtime marker is present, detection resolves innermost-first: `$TMUX` is checked before `HERDR_ENV=1`, which is checked before cmux-tui's `CMUX_TUI_SOCKET`/`CMUX_MUX_SOCKET`, which is checked before cmux's primary `CMUX_WORKSPACE_ID` marker and its documented fallback signals - tmux or herdr started from inside a cmux or cmux-tui terminal is the innermost, currently-executing layer, a cmux-tui session started inside a cmux GUI tab still resolves to cmux-tui because the GUI marker is inherited from outside, and the cmux GUI app (a terminal application, not a nestable multiplexer) is always checked last.
 See [`docs/cmux-backend.md`](cmux-backend.md#runtime-detection) for why cmux can be selected when `CMUX_WORKSPACE_ID` is absent.
-Auto-detected herdr or cmux prints a stderr notice naming `config/backend` and `--backend tmux` as opt-outs; auto-detected tmux stays silent to preserve existing default behavior.
+Auto-detected herdr, cmux-tui, or cmux prints a stderr notice naming `config/backend` and `--backend tmux` as opt-outs; auto-detected tmux stays silent to preserve existing default behavior.
 Zellij and Orca are never auto-detected; select them by putting the name in a local `config/backend` file, by exporting `FM_BACKEND=<name>`, or by telling the first mate in chat.
-Any value other than `tmux`, `herdr`, `zellij`, `orca`, or `cmux` is rejected until another adapter is implemented and verified.
-`fm-spawn.sh` accepts `tmux`, `herdr`, `zellij`, `orca`, and `cmux` for ship and scout tasks; `backend=orca` and `backend=cmux` both still refuse `--secondmate` until secondmate launch semantics are designed for each.
+Any value other than `tmux`, `herdr`, `zellij`, `orca`, `cmux`, or `cmux-tui` is rejected until another adapter is implemented and verified.
+`fm-spawn.sh` accepts `tmux`, `herdr`, `zellij`, `orca`, `cmux`, and `cmux-tui` for ship and scout tasks; `backend=orca`, `backend=cmux`, and `backend=cmux-tui` all still refuse `--secondmate` until secondmate launch semantics are designed for each.
 `codex-app` is not an accepted runtime backend yet; [`docs/codex-app-backend.md`](codex-app-backend.md) owns the Codex App boundary.
 The session-start secondmate liveness sweep uses the recovery-grade `fm_backend_agent_state` classifier where verified.
 The comment above that function in `bin/fm-backend.sh` is the single owner of its detailed state contract and recovery authorization.
@@ -79,6 +79,7 @@ The compatibility helper `fm_backend_agent_alive` continues to collapse those de
 A herdr spawn additionally version-gates against the installed `herdr` binary's protocol and requires `jq`, refusing loudly on an incompatible or missing installation.
 A zellij spawn additionally version-gates against the installed `zellij` binary's version and requires `jq`, refusing loudly when either is missing or the version is older than 0.44.
 A cmux spawn additionally version-gates against the installed `cmux` binary's version, requires `jq`, and requires the control socket to be reachable and accessible (see [`docs/cmux-backend.md`](cmux-backend.md) "Setup" for the one-time socket-access configuration this needs; Automation mode is the recommended socket control mode, with Password mode supported via `config/cmux-socket-password`), refusing loudly and non-retryably on a `cmuxOnly`/unauthenticated socket.
+A cmux-tui spawn additionally version-gates against the installed `cmux-tui` binary's version and requires `jq`, refusing loudly when either is missing or the version is older than 0.1; there is no socket-access configuration because the per-uid session socket is same-user by default (see [`docs/cmux-tui-backend.md`](cmux-tui-backend.md) "Setup").
 A backend spawn refusal from a missing dependency, version gate, or unauthenticated socket is terminal for that selected backend; firstmate surfaces it as a blocker instead of silently retrying another backend.
 Task meta records `backend=` only for a non-default backend; an absent `backend=` means `tmux`, preserving existing default-path meta files.
 Every new task records `endpoint_task_id=` as the cleanup binding between the metadata filename and its opaque runtime endpoint.
@@ -229,6 +230,8 @@ For the zellij backend, `FM_HOME` does not split containers, but it determines t
 The full zellij home label also includes a short hash of the resolved `FM_ROOT` path.
 For the cmux backend, `FM_CONFIG_OVERRIDE` overrides where `config/cmux-socket-password` is read from, while `FM_HOME` determines the default config path and readable home prefix embedded in workspace titles.
 The full cmux home label also includes a short hash of the resolved `FM_ROOT` path, and there is no per-home container split.
+For the cmux-tui backend, `FM_HOME` determines the home-scoped session name, the adapter-owned config file, and the durable server state dir; `FM_CMUXTUI_SESSION`, `FM_CMUXTUI_CONFIG`, and `FM_CMUXTUI_STATE` override each for test isolation.
+The full cmux-tui session name also includes a short hash of the resolved `FM_ROOT` path, and the session itself is the per-home container split.
 
 ## Harness support
 
@@ -639,13 +642,17 @@ FM_DATA_OVERRIDE=        # alternate data dir, mainly for tests
 FM_PROJECTS_OVERRIDE=    # alternate projects dir, mainly for tests
 FM_CONFIG_OVERRIDE=      # alternate config dir, mainly for tests
 FM_PROC_ROOT_OVERRIDE=   # alternate /proc root for Linux process-identity reads in fm-wake-lib.sh and fm-teardown.sh, mainly for tests
-FM_BACKEND=             # optional runtime backend override for new spawns; tmux/herdr/zellij/orca/cmux support ship/scout spawns, codex-app is not accepted
+FM_BACKEND=             # optional runtime backend override for new spawns; tmux/herdr/zellij/orca/cmux/cmux-tui support ship/scout spawns, codex-app is not accepted
 FM_TRACE_CONTEXT=       # optional trace-context override; see "Trace context propagation"
 HERDR_SESSION=default  # herdr-only: named session for normal backend ops; not enough for destructive cleanup (docs/herdr-backend.md)
 FM_BACKEND_HERDR_SUBMIT_POLLS=6  # herdr-only: agent-state samples spread across each Enter attempt's budget when confirming a submit (docs/herdr-backend.md "Current transport behavior")
 FM_BACKEND_HERDR_SUBMIT_MIN_SLEEP=0.6  # herdr-only: minimum per-Enter confirmation budget before polling agent-state after an idle baseline
 FM_ZELLIJ_SESSION=firstmate  # zellij-only: named session for normal backend ops and test isolation (docs/zellij-backend.md)
 CMUX_SOCKET_PASSWORD=   # cmux-only: socket password fallback when config/cmux-socket-password is absent (docs/cmux-backend.md)
+FM_CMUXTUI_BIN=         # cmux-tui-only: explicit path to the cmux-tui binary when it is not on PATH (docs/cmux-tui-backend.md)
+FM_CMUXTUI_SESSION=     # cmux-tui-only: session-name override for test isolation; default is the home-scoped fm-<home-label> session (docs/cmux-tui-backend.md)
+FM_CMUXTUI_CONFIG=      # cmux-tui-only: adapter-owned CMUX_TUI_CONFIG file override for test isolation; default state/cmux-tui/cmux-tui.json (docs/cmux-tui-backend.md)
+FM_CMUXTUI_STATE=       # cmux-tui-only: durable server --state dir override for test isolation; default state/cmux-tui (docs/cmux-tui-backend.md)
 FM_SESSION_START_STATUS_TAIL=5   # state/*.status lines printed per task in the session-start digest; each line is capped by bin/fm-line-cap-lib.sh
 FM_SESSION_START_QUEUED_LIMIT=20   # plain queued backlog rows in the session-start digest; in-flight, held, and blocked rows are never bounded and done rows are never listed
 FM_BOOTSTRAP_DETECT_ONLY=0   # internal/read-only session-start mode: skip bootstrap's mutating sweeps and print advisory TANGLE wording
diff --git a/docs/documentation-audiences.json b/docs/documentation-audiences.json
index bceee95935c..e286d4254fc 100644
--- a/docs/documentation-audiences.json
+++ b/docs/documentation-audiences.json
@@ -98,6 +98,10 @@
       "source": "docs/cmux-backend.md",
       "target": "docs/verification/runtime-backends.md"
     },
+    {
+      "source": "docs/cmux-tui-backend.md",
+      "target": "docs/verification/runtime-backends.md"
+    },
     {
       "source": "docs/codex-app-backend.md",
       "target": "docs/verification/runtime-backends.md"
@@ -244,6 +248,10 @@
       "path": "docs/cmux-backend.md",
       "audience": "operator-current"
     },
+    {
+      "path": "docs/cmux-tui-backend.md",
+      "audience": "operator-current"
+    },
     {
       "path": "docs/codex-app-backend.md",
       "audience": "operator-current"
diff --git a/docs/verification/runtime-backends.md b/docs/verification/runtime-backends.md
index 0e918ad5c46..b5403ef6581 100644
--- a/docs/verification/runtime-backends.md
+++ b/docs/verification/runtime-backends.md
@@ -762,6 +762,49 @@ FM_CMUX_CLAUDE_COMPOSER_LIVE=1 bin/fm-test-run.sh tests/fm-cmux-claude-composer-
 That guard still addresses the worker by task selector, so it no longer reaches the typed submit path and is not a current refresh entry point for this guarantee.
 The portable classifier regression is `tests/fm-backend-cmux.test.sh`.
 
+## cmux-tui
+
+The current compatibility floor is cmux-tui 0.1, and the active live evidence uses 0.1.0 at commit 4471965b12 on macOS aarch64, 2026-08-24.
+Real tests use only an isolated throwaway session (`FM_CMUXTUI_SESSION=fm-tui-test-*`), a scratch `--state` dir, `fm-test-` labels, and an adapter-owned `CMUX_TUI_CONFIG`, and they stop the session they started.
+
+```sh
+cmux-tui --version
+```
+
+Observed version:
+
+```text
+cmux 0.1.0 (4471965b12d19914793f46f96322fff5815da010; ghostty f76c132e526f124fe4aaebd39f516751656844bc)
+```
+
+Current active CLI findings:
+
+| Guarantee | Command shape | Result |
+| --- | --- | --- |
+| Headless session | `server start --session <name> --headless --state <dir>` | Started a dedicated session with a 0700 per-uid socket and no auth handshake. |
+| Create | `workspace create --name <label> --empty --json`, `tab create terminal --workspace <id> --cwd <dir> --json` | Returned typed `ws_`/`term_` ids in `.value`. |
+| Duplicate names | two `workspace create --name <same>` | Both succeeded; uniqueness is not enforced natively. |
+| Fresh read | `terminal <id> screen read --json` before any write | Returned text plus `cursor_row`/`cursor_col`/`cursor_visible`. |
+| Literal send | `terminal <id> write --text <text>` | Left text unsubmitted. |
+| Keys | `terminal <id> keys enter\|escape\|ctrl+c\|ctrl+d\|ctrl+u\|tab\|up\|down` | All accepted; an invalid chord returned typed `validation.invalid`. |
+| Pattern wait | `terminal <id> screen wait --pattern <regex> --timeout-ms 3000` | Returned `matched:true` with the matching line. |
+| Scrollback | `terminal <id> history read --json` | Retained rows were contiguous with the visible screen (last history row immediately preceded the screen's first row) with `next:null` at ~900 rows. |
+| Live cwd | `terminal <id> process show --json` | Reported the top-level shell's cwd as `file://<host>/path` plus child pids. |
+| Frozen subshell cwd counterexample | `env -i /bin/bash --norc` then `cd /usr/local` inside it | The structured cwd stayed at the launch directory while `lsof -a -p <child> -d cwd -Fn` reported `/usr/local`. |
+| Last workspace | `workspace <id> close` on the session's only workspace | Closed it; `workspace list` returned `[]` and `server status` stayed `running`. |
+| Durable ids | `server stop` then `server start --state <same dir>` | `workspace list` and `terminal <id> show` returned the identical `ws_`/`term_` ids, with the terminal running. |
+| Correlation replay | `workspace create --correlation-key <k>` twice | The second call returned `replayed:true` with the original workspace id, including after that workspace was closed - keys must be per-attempt nonces. |
+| Typed errors | close of a missing workspace, invalid key chord | Returned `{code, message, retryable, details}` (`selector.not_found`, `validation.invalid`); an interrupted mutation surfaced `mutation.indeterminate` with an idempotency key. |
+| Agent state | `agent report --terminal <id> --state working --source hook`, `agent list --json` | Rows carry `working\|blocked\|idle\|done\|unknown` per terminal with `updated_at_ms`. |
+| Runtime marker | `env` inside a spawned terminal | `CMUX_TUI_SOCKET` and legacy `CMUX_MUX_SOCKET` point at the session socket, alongside `CMUX_TUI_SESSION_ID`/`CMUX_TUI_TERMINAL_ID`; a session inside a cmux GUI tab also inherits the GUI's `CMUX_WORKSPACE_ID`, which is why detection checks cmux-tui first. |
+
+```sh
+tests/fm-backend-cmux-tui.test.sh
+tests/fm-backend-cmux-tui-smoke.test.sh
+```
+
+The real smoke proves headless session bring-up, create and duplicate refusal, label verification, two-step literal-then-Enter submit, bounded capture with scrollback, cursor-anchored composer classification, hook-fed busy state, structured current-path including the subshell counterexample, last-workspace close, durable-id restart recovery, and guarded exact cleanup of the throwaway session.
+
 ## Codex App host tools
 
 A reusable Desktop host-tool smoke ran on 2026-07-06 against Codex Desktop bundle version 26.623.101652, build 4674, bundle id `com.openai.codex`.