From 073011c8c6c8a33281e63ced6d979352e156d070 Mon Sep 17 00:00:00 2001
From: Kadriya Bazarova <Kadriya89@users.noreply.github.com>
Date: Tue, 7 Jul 2026 23:26:25 -0500
Subject: [PATCH 1/9] fix(backends): pass FIREWORKS_API_KEY through to opencode
 cmux spawns

cmux workspaces get none of firstmate's own process environment, so an
opencode crewmate spawned via the cmux backend never saw
FIREWORKS_API_KEY and its Fireworks-backed models (e.g. GLM 5.2) failed
outright. fm_backend_cmux_create_task now takes the resolved harness,
fetches the key from AWS Secrets Manager (opencode/fireworks-api-key,
us-east-1) using whatever AWS profile is ambient, and passes it to
`cmux new-workspace` as --env FIREWORKS_API_KEY=<value> - the flag
cmux-control's own cmuxctl already uses for this. The secret only ever
lands in a shell variable, never printed or logged. Fixed along the way:
an empty-array expansion under `set -u` that bash 3.2 treats as an
unbound-variable error, caught by the real-cmux smoke test.
---
 bin/backends/cmux.sh          |  72 +++++++++++++++++--
 bin/fm-spawn.sh               |   2 +-
 docs/cmux-backend.md          |  11 +++
 tests/fm-backend-cmux.test.sh | 130 ++++++++++++++++++++++++++++++++++
 4 files changed, 209 insertions(+), 6 deletions(-)

diff --git a/bin/backends/cmux.sh b/bin/backends/cmux.sh
index 69dc0b53b..56a44b1ed 100644
--- a/bin/backends/cmux.sh
+++ b/bin/backends/cmux.sh
@@ -341,6 +341,57 @@ fm_backend_cmux_surface_id_for_workspace() {  # <workspace_id>
     | jq -r '.panes[0] // {} | .selected_surface_id // (.surface_ids[0] // empty)' 2>/dev/null
 }
 
+# fm_backend_cmux_secret_specs_for_harness: zero or more "ENV_VAR
+# secret-name" lines naming the provider credentials that must be explicitly
+# injected into a cmux workspace for <harness>. Needed only for cmux: unlike
+# tmux/herdr/zellij (which fork a task inside the same host shell and so
+# inherit firstmate's own process environment), a cmux terminal surface's
+# environment is heavily scrubbed at spawn time (docs/cmux-backend.md
+# "Provider credential passthrough (--env)") - ambient provider API keys
+# never reach it. One pairing exists today: opencode's Fireworks-backed
+# models (e.g. GLM 5.2) need FIREWORKS_API_KEY. Expressed as a lookup table
+# so a second pairing is a one-line addition rather than a new framework.
+fm_backend_cmux_secret_specs_for_harness() {  # <harness>
+  case "$1" in
+    opencode) printf 'FIREWORKS_API_KEY opencode/fireworks-api-key\n' ;;
+  esac
+}
+
+# fm_backend_cmux_fetch_secret: print <secret-name>'s current value from AWS
+# Secrets Manager (region us-east-1) on stdout, using whatever AWS
+# credentials/profile are already ambient in this process's environment -
+# never a hardcoded profile. Fails loudly rather than continuing without the
+# key: a missing 'aws' CLI, a failed call (including no credentials
+# configured), or an empty secret are all refused.
+fm_backend_cmux_fetch_secret() {  # <secret-name>
+  local secret_name=$1 value
+  command -v aws >/dev/null 2>&1 || { echo "error: cmux env passthrough needs secret '$secret_name' but the 'aws' CLI is not installed" >&2; return 1; }
+  value=$(aws secretsmanager get-secret-value --secret-id "$secret_name" --region us-east-1 --query SecretString --output text 2>/dev/null) \
+    || { echo "error: failed to fetch secret '$secret_name' from AWS Secrets Manager (region us-east-1) - check that AWS credentials/profile are configured" >&2; return 1; }
+  [ -n "$value" ] && [ "$value" != None ] || { echo "error: secret '$secret_name' from AWS Secrets Manager returned an empty value" >&2; return 1; }
+  printf '%s' "$value"
+}
+
+# fm_backend_cmux_env_args_for_harness: resolve <harness>'s secret specs (if
+# any, per fm_backend_cmux_secret_specs_for_harness) and set
+# FM_BACKEND_CMUX_ENV_ARGS to the "--env KEY=VALUE" pairs to pass to
+# `new-workspace`. A fetched value only ever lands in this array - never
+# printed, logged, or written to a file - mirroring how
+# fm_backend_cmux_password/CMUX_SOCKET_PASSWORD above handles the socket
+# password. Empty array (success) when the harness needs no injected secret.
+fm_backend_cmux_env_args_for_harness() {  # <harness>
+  FM_BACKEND_CMUX_ENV_ARGS=()
+  local harness=$1 spec env_var secret_name value
+  while IFS= read -r spec; do
+    [ -n "$spec" ] || continue
+    env_var=${spec%% *}
+    secret_name=${spec#* }
+    value=$(fm_backend_cmux_fetch_secret "$secret_name") || return 1
+    FM_BACKEND_CMUX_ENV_ARGS+=(--env "$env_var=$value")
+  done < <(fm_backend_cmux_secret_specs_for_harness "$harness")
+  return 0
+}
+
 # fm_backend_cmux_create_task: create the task's workspace (one surface),
 # refusing an existing live <label> (finding #6: cmux enforces no uniqueness
 # itself). Resolves the fresh workspace's default surface via one list-panes
@@ -348,17 +399,28 @@ fm_backend_cmux_surface_id_for_workspace() {  # <workspace_id>
 # so no separate new-surface call is needed). --focus false is passed for
 # defense in depth though verified to already be the default (finding:
 # workspace/surface/pane create all default focus to false) - no
-# focus-restore dance is needed, unlike zellij. Echoes "<workspace_id>
-# <surface_id>" on success.
-fm_backend_cmux_create_task() {  # <label> <cwd>
-  local label=$1 cwd=$2 title dup out wsid sfid
+# focus-restore dance is needed, unlike zellij. When <harness> is given and
+# needs provider credentials (fm_backend_cmux_secret_specs_for_harness), they
+# are fetched and passed as `--env KEY=VALUE` (verified flag: cmux-control's
+# own bin/cmuxctl, cmuxNewWorkspace). Echoes "<workspace_id> <surface_id>" on
+# success.
+fm_backend_cmux_create_task() {  # <label> <cwd> [harness]
+  local label=$1 cwd=$2 harness=${3:-} title dup out wsid sfid
   title=$(fm_backend_cmux_scoped_title "$label")
   dup=$(fm_backend_cmux_workspace_id_for_label "$title")
   if [ -n "$dup" ]; then
     echo "error: cmux workspace '$title' already exists" >&2
     return 1
   fi
-  out=$(fm_backend_cmux_cli new-workspace --name "$title" --cwd "$cwd" --focus false --id-format uuids 2>&1) || {
+  fm_backend_cmux_env_args_for_harness "$harness" || return 1
+  # Guarded append, never a bare "${arr[@]}" expansion of a possibly-empty
+  # array: under `set -u`, bash 3.2 (the macOS system bash) treats expanding a
+  # zero-element array as an unbound-variable error, and most callers spawn
+  # with no harness secret needed (FM_BACKEND_CMUX_ENV_ARGS stays empty).
+  local -a new_workspace_args=(new-workspace --name "$title" --cwd "$cwd")
+  [ "${#FM_BACKEND_CMUX_ENV_ARGS[@]}" -eq 0 ] || new_workspace_args+=("${FM_BACKEND_CMUX_ENV_ARGS[@]}")
+  new_workspace_args+=(--focus false --id-format uuids)
+  out=$(fm_backend_cmux_cli "${new_workspace_args[@]}" 2>&1) || {
     echo "error: cmux new-workspace failed for '$title': $out" >&2
     return 1
   }
diff --git a/bin/fm-spawn.sh b/bin/fm-spawn.sh
index c973e4416..989839090 100755
--- a/bin/fm-spawn.sh
+++ b/bin/fm-spawn.sh
@@ -760,7 +760,7 @@ EOF
     ;;
   cmux)
     fm_backend_cmux_container_ensure || exit 1
-    CMUX_TASK_IDS=$(fm_backend_cmux_create_task "$W" "$PROJ_ABS") || exit 1
+    CMUX_TASK_IDS=$(fm_backend_cmux_create_task "$W" "$PROJ_ABS" "$HARNESS") || exit 1
     read -r CMUX_WORKSPACE_ID CMUX_SURFACE_ID <<EOF
 $CMUX_TASK_IDS
 EOF
diff --git a/docs/cmux-backend.md b/docs/cmux-backend.md
index 5859e7f2d..c97ade4e6 100644
--- a/docs/cmux-backend.md
+++ b/docs/cmux-backend.md
@@ -327,6 +327,17 @@ Same as herdr's tabs and zellij's tabs, unlike tmux's own window-name uniqueness
 Verified live: two workspaces created with the identical title `fm-test-dup` both succeeded and listed simultaneously with distinct ids; two surfaces within one workspace both renamed to the identical tab title also succeeded.
 `fm_backend_cmux_create_task`'s own title-based duplicate check is therefore required, mirroring both prior adapters' posture exactly.
 
+## Provider credential passthrough (`--env`)
+
+A cmux workspace's terminal surface starts with none of firstmate's own process environment worth relying on for provider credentials - unlike tmux/herdr/zellij, which fork a task inside the same host shell and so inherit it, a cmux surface is a fresh GUI-app-spawned process (see the wrapper-stripping finding above for a related, but distinct, case: that one is about the RUNTIME firstmate's own launch environment when firstmate itself runs inside a cmux tab; this one is about the environment of a workspace firstmate just CREATED for a task).
+So an ambient `FIREWORKS_API_KEY` set in firstmate's own shell never reaches a spawned opencode surface, and opencode's Fireworks-backed models (e.g. GLM 5.2) fail outright.
+
+`fm_backend_cmux_create_task` takes an optional third `<harness>` argument and, when that harness needs a provider credential (`fm_backend_cmux_secret_specs_for_harness` - one pairing today, `opencode` -> `FIREWORKS_API_KEY`), fetches it from AWS Secrets Manager (`opencode/fireworks-api-key`, region `us-east-1`, using whatever AWS credentials/profile are already ambient - never a hardcoded profile) and passes it to `new-workspace` as `--env FIREWORKS_API_KEY=<value>`.
+`--env KEY=VALUE` is cmux-control's own verified mechanism for this (`bin/cmuxctl`'s `cmuxNewWorkspace`, which builds one `--env` pair per entry of an `env` object): a real, working `new-workspace` flag firstmate's own adapter simply never used before.
+A failed fetch (missing `aws` CLI, no credentials configured, an empty secret) fails the spawn loudly rather than silently launching opencode without the key it needs.
+The fetched value only ever lands in a shell variable used to build the `--env` argument - never printed, logged, or written to a file - the same convention `fm_backend_cmux_password`/`CMUX_SOCKET_PASSWORD` above already follows for the socket password.
+`bin/fm-spawn.sh` passes the resolved `$HARNESS` through on every cmux spawn; a harness with no configured secret spec (everything except opencode today) triggers no AWS call at all.
+
 ## Composer verification: structural border-row classification (adapted from herdr)
 
 cmux's `read-screen` gives plain-text capture with no cursor-row primitive and no ANSI style channel, unlike tmux's `#{cursor_y}` and herdr's `--format ansi` path for ANSI-aware ghost/placeholder classification.
diff --git a/tests/fm-backend-cmux.test.sh b/tests/fm-backend-cmux.test.sh
index 79c16b13a..2bac53dc6 100755
--- a/tests/fm-backend-cmux.test.sh
+++ b/tests/fm-backend-cmux.test.sh
@@ -65,6 +65,31 @@ SH
   printf '%s\n' "$fb"
 }
 
+# add_fake_aws: drop an `aws` stub into an existing fakebin <dir> (typically
+# one already holding a fake `cmux` from make_cmux_fakebin), so opencode
+# create_task tests can fake both tools from one PATH entry. Logs every
+# invocation (one line, unit-separated args) to $FM_AWS_LOG and either exits
+# $FM_AWS_FAKE_EXIT (default 0) or prints $FM_AWS_FAKE_SECRET (default
+# 'fake-fireworks-key') on stdout, mirroring make_cmux_fakebin's
+# log-and-canned-response convention. Never a real network call.
+add_fake_aws() {  # <fakebin-dir>
+  local fb=$1
+  cat > "$fb/aws" <<'SH'
+#!/usr/bin/env bash
+set -u
+LOG="${FM_AWS_LOG:?}"
+{
+  printf 'aws'
+  for a in "$@"; do printf '\x1f%s' "$a"; done
+  printf '\n'
+} >> "$LOG"
+exit_code=${FM_AWS_FAKE_EXIT:-0}
+[ "$exit_code" -eq 0 ] || exit "$exit_code"
+printf '%s' "${FM_AWS_FAKE_SECRET:-fake-fireworks-key}"
+SH
+  chmod +x "$fb/aws"
+}
+
 cmux_workspace_list_response() {  # <dir> <n> <id1> <title1> [<id2> <title2> ...]
   local dir=$1 n=$2 json first=1
   shift 2
@@ -496,6 +521,106 @@ test_create_task_creates_and_parses_ids() {
   pass "fm_backend_cmux_create_task: creates a workspace and parses workspace_id/surface_id from list responses"
 }
 
+# --- create_task: opencode Fireworks env passthrough (--env) -----------------
+#
+# cmux workspaces get none of firstmate's own process environment (heavily
+# scrubbed at spawn time, docs/cmux-backend.md "Environment scrubbing"), so an
+# opencode spawn needs FIREWORKS_API_KEY injected explicitly via `new-workspace
+# --env KEY=VALUE`. These tests fake both `cmux` and `aws` (add_fake_aws) so no
+# real AWS call is ever made.
+
+test_secret_specs_for_harness_maps_opencode_only() {
+  ( . "$ROOT/bin/backends/cmux.sh"
+    out=$(fm_backend_cmux_secret_specs_for_harness opencode)
+    [ "$out" = "FIREWORKS_API_KEY opencode/fireworks-api-key" ] || { echo "opencode spec mismatch: '$out'" >&2; exit 1; }
+    out=$(fm_backend_cmux_secret_specs_for_harness claude)
+    [ -z "$out" ] || { echo "claude should need no injected secret, got '$out'" >&2; exit 1; }
+  ) || fail "fm_backend_cmux_secret_specs_for_harness did not map exactly opencode -> FIREWORKS_API_KEY/opencode/fireworks-api-key"
+  pass "fm_backend_cmux_secret_specs_for_harness: maps opencode to FIREWORKS_API_KEY/opencode/fireworks-api-key and other harnesses to nothing"
+}
+
+test_create_task_passes_fireworks_env_for_opencode() {
+  local dir fb out title
+  dir="$TMP_ROOT/create-task-opencode-env"; mkdir -p "$dir/responses"
+  title=$(cmux_expected_scoped_title fm-oc1)
+  # 1: workspace list --json (pre-create duplicate check) -> no match
+  printf '{"workspaces":[]}' > "$dir/responses/1.out"
+  # 2: new-workspace (silent on success)
+  # 3: workspace list --json (post-create id resolution) -> match
+  cmux_workspace_list_response "$dir" 3 "bbbbbbbb-1111-1111-1111-111111111111" "$title"
+  # 4: list-panes --json --id-format uuids -> default surface id
+  cmux_panes_response "$dir" 4 "cccccccc-2222-2222-2222-222222222222"
+  fb=$(make_cmux_fakebin "$dir")
+  add_fake_aws "$fb"
+  out=$( PATH="$fb:$PATH" FM_CMUX_LOG="$dir/log" FM_CMUX_RESPONSES="$dir/responses" \
+    FM_AWS_LOG="$dir/aws-log" FM_AWS_FAKE_SECRET="s3cr3t-fireworks-key" \
+    bash -c '. "$0/bin/backends/cmux.sh"; fm_backend_cmux_create_task fm-oc1 /tmp/proj opencode' "$ROOT" )
+  [ "$out" = "bbbbbbbb-1111-1111-1111-111111111111 cccccccc-2222-2222-2222-222222222222" ] \
+    || fail "create_task should still echo '<workspace_id> <surface_id>' (never the secret) for an env-injected opencode spawn, got '$out'"
+  assert_contains "$(cat "$dir/log")" $'\x1f''--env'$'\x1f''FIREWORKS_API_KEY=s3cr3t-fireworks-key' \
+    "create_task did not pass --env FIREWORKS_API_KEY=<value> to new-workspace for an opencode harness"
+  assert_contains "$(cat "$dir/aws-log")" \
+    $'\x1f''secretsmanager'$'\x1f''get-secret-value'$'\x1f''--secret-id'$'\x1f''opencode/fireworks-api-key'$'\x1f''--region'$'\x1f''us-east-1' \
+    "create_task did not fetch the Fireworks key from the documented Secrets Manager secret/region"
+  assert_not_contains "$(cat "$dir/aws-log")" "profile" \
+    "create_task's secret fetch should not hardcode an AWS profile"
+  pass "fm_backend_cmux_create_task: passes --env FIREWORKS_API_KEY=<value> to new-workspace for an opencode spawn"
+}
+
+test_create_task_omits_env_for_non_opencode_harness() {
+  local dir fb out title
+  dir="$TMP_ROOT/create-task-claude-no-env"; mkdir -p "$dir/responses"
+  title=$(cmux_expected_scoped_title fm-cl1)
+  printf '{"workspaces":[]}' > "$dir/responses/1.out"
+  cmux_workspace_list_response "$dir" 3 "bbbbbbbb-1111-1111-1111-111111111111" "$title"
+  cmux_panes_response "$dir" 4 "cccccccc-2222-2222-2222-222222222222"
+  fb=$(make_cmux_fakebin "$dir")
+  cat > "$fb/aws" <<'SH'
+#!/usr/bin/env bash
+echo "aws should not be invoked for a harness that needs no injected secret" >&2
+exit 1
+SH
+  chmod +x "$fb/aws"
+  out=$( PATH="$fb:$PATH" FM_CMUX_LOG="$dir/log" FM_CMUX_RESPONSES="$dir/responses" \
+    bash -c '. "$0/bin/backends/cmux.sh"; fm_backend_cmux_create_task fm-cl1 /tmp/proj claude' "$ROOT" )
+  [ "$out" = "bbbbbbbb-1111-1111-1111-111111111111 cccccccc-2222-2222-2222-222222222222" ] \
+    || fail "create_task should still succeed for a harness that needs no injected secret"
+  assert_not_contains "$(cat "$dir/log")" $'\x1f''--env' \
+    "create_task should not pass --env for a harness with no configured secret spec"
+  pass "fm_backend_cmux_create_task: passes no --env flags, and never calls aws, for a harness with no configured secret (e.g. claude)"
+}
+
+test_create_task_fails_when_secret_fetch_fails() {
+  local dir fb out status
+  dir="$TMP_ROOT/create-task-secret-fail"; mkdir -p "$dir/responses"
+  # 1: workspace list --json (pre-create duplicate check) -> no match
+  printf '{"workspaces":[]}' > "$dir/responses/1.out"
+  fb=$(make_cmux_fakebin "$dir")
+  add_fake_aws "$fb"
+  out=$( PATH="$fb:$PATH" FM_CMUX_LOG="$dir/log" FM_CMUX_RESPONSES="$dir/responses" \
+    FM_AWS_LOG="$dir/aws-log" FM_AWS_FAKE_EXIT=1 \
+    bash -c '. "$0/bin/backends/cmux.sh"; fm_backend_cmux_create_task fm-oc-fail /tmp/proj opencode' "$ROOT" 2>&1 )
+  status=$?
+  [ "$status" -ne 0 ] || fail "create_task should fail when the Fireworks secret cannot be fetched, rather than spawning without it"
+  assert_not_contains "$(cat "$dir/log")" $'\x1f''new-workspace' \
+    "create_task should never call new-workspace when the required secret fetch failed"
+  assert_contains "$out" "opencode/fireworks-api-key" "create_task's failure did not name the secret it could not fetch"
+  pass "fm_backend_cmux_create_task: fails before creating the workspace when the required secret cannot be fetched"
+}
+
+test_fetch_secret_fails_when_aws_missing() {
+  local dir out status
+  dir="$TMP_ROOT/fetch-secret-no-aws"; mkdir -p "$dir/empty-fakebin"
+  # Same empty-PATH convention as test_version_check_refuses_missing_cmux:
+  # excludes /opt/homebrew/bin and any other dir a real aws CLI might live in.
+  out=$( PATH="$dir/empty-fakebin:/usr/bin:/bin" \
+    bash -c '. "$0/bin/backends/cmux.sh"; fm_backend_cmux_fetch_secret opencode/fireworks-api-key' "$ROOT" 2>&1 )
+  status=$?
+  [ "$status" -ne 0 ] || fail "fetch_secret should fail when the aws CLI is not installed"
+  assert_contains "$out" "aws" "fetch_secret's missing-CLI error did not mention aws"
+  pass "fm_backend_cmux_fetch_secret: fails loudly when the aws CLI is not installed, rather than continuing without the key"
+}
+
 # --- target_ready / capture ---------------------------------------------------
 
 test_target_ready_fails_when_target_absent() {
@@ -1033,6 +1158,11 @@ test_ensure_running_fails_fast_on_denied_without_launching
 test_ensure_running_fails_fast_on_unauth_without_launching
 test_create_task_refuses_duplicate_label
 test_create_task_creates_and_parses_ids
+test_secret_specs_for_harness_maps_opencode_only
+test_create_task_passes_fireworks_env_for_opencode
+test_create_task_omits_env_for_non_opencode_harness
+test_create_task_fails_when_secret_fetch_fails
+test_fetch_secret_fails_when_aws_missing
 test_target_ready_fails_when_target_absent
 test_target_ready_checks_expected_label
 test_target_ready_rejects_label_mismatch

From 2bff74ea271636e871134fcbc983fa6d50de1201 Mon Sep 17 00:00:00 2001
From: Kadriya Bazarova <Kadriya89@users.noreply.github.com>
Date: Wed, 8 Jul 2026 13:04:16 -0500
Subject: [PATCH 2/9] no-mistakes(review): redact fetched secret from cmux
 new-workspace failure output

---
 bin/backends/cmux.sh          |  7 +++++++
 tests/fm-backend-cmux.test.sh | 39 +++++++++++++++++++++++++++++++++++
 2 files changed, 46 insertions(+)

diff --git a/bin/backends/cmux.sh b/bin/backends/cmux.sh
index 56a44b1ed..075d0687a 100644
--- a/bin/backends/cmux.sh
+++ b/bin/backends/cmux.sh
@@ -421,6 +421,13 @@ fm_backend_cmux_create_task() {  # <label> <cwd> [harness]
   [ "${#FM_BACKEND_CMUX_ENV_ARGS[@]}" -eq 0 ] || new_workspace_args+=("${FM_BACKEND_CMUX_ENV_ARGS[@]}")
   new_workspace_args+=(--focus false --id-format uuids)
   out=$(fm_backend_cmux_cli "${new_workspace_args[@]}" 2>&1) || {
+    if [ "${#FM_BACKEND_CMUX_ENV_ARGS[@]}" -gt 0 ]; then
+      local env_arg
+      for env_arg in "${FM_BACKEND_CMUX_ENV_ARGS[@]}"; do
+        [ "$env_arg" = --env ] && continue
+        out=${out//"${env_arg#*=}"/[redacted]}
+      done
+    fi
     echo "error: cmux new-workspace failed for '$title': $out" >&2
     return 1
   }
diff --git a/tests/fm-backend-cmux.test.sh b/tests/fm-backend-cmux.test.sh
index 2bac53dc6..7fdb0f1de 100755
--- a/tests/fm-backend-cmux.test.sh
+++ b/tests/fm-backend-cmux.test.sh
@@ -608,6 +608,44 @@ test_create_task_fails_when_secret_fetch_fails() {
   pass "fm_backend_cmux_create_task: fails before creating the workspace when the required secret cannot be fetched"
 }
 
+test_create_task_failure_output_redacts_fetched_secret() {
+  local dir fb out status
+  dir="$TMP_ROOT/create-task-secret-redact"; mkdir -p "$dir/responses"
+  fb=$(make_cmux_fakebin "$dir")
+  add_fake_aws "$fb"
+  # A `cmux` stub whose new-workspace fails with a usage-style error that
+  # echoes the full invocation back - the exact leak path this test guards:
+  # the --env FIREWORKS_API_KEY=<value> argument must never reach firstmate's
+  # own stderr through create_task's raw-output error message.
+  cat > "$fb/cmux" <<'SH'
+#!/usr/bin/env bash
+set -u
+if [ "${1:-}" = workspace ]; then
+  printf '{"workspaces":[]}'
+  exit 0
+fi
+if [ "${1:-}" = new-workspace ]; then
+  printf 'error: invalid arguments:' >&2
+  for a in "$@"; do printf ' %s' "$a" >&2; done
+  printf '\n' >&2
+  exit 1
+fi
+exit 0
+SH
+  chmod +x "$fb/cmux"
+  out=$( PATH="$fb:$PATH" FM_CMUX_LOG="$dir/log" FM_CMUX_RESPONSES="$dir/responses" \
+    FM_AWS_LOG="$dir/aws-log" FM_AWS_FAKE_SECRET="s3cr3t-fireworks-key" \
+    bash -c '. "$0/bin/backends/cmux.sh"; fm_backend_cmux_create_task fm-oc-redact /tmp/proj opencode' "$ROOT" 2>&1 )
+  status=$?
+  [ "$status" -ne 0 ] || fail "create_task should fail when new-workspace fails"
+  assert_contains "$out" "new-workspace failed" "create_task did not report the new-workspace failure"
+  assert_not_contains "$out" "s3cr3t-fireworks-key" \
+    "create_task's new-workspace failure message leaked the fetched secret value"
+  assert_contains "$out" "[redacted]" \
+    "create_task's new-workspace failure message should redact the secret value, not drop the diagnostics"
+  pass "fm_backend_cmux_create_task: redacts the fetched secret from a failed new-workspace's echoed-back error output"
+}
+
 test_fetch_secret_fails_when_aws_missing() {
   local dir out status
   dir="$TMP_ROOT/fetch-secret-no-aws"; mkdir -p "$dir/empty-fakebin"
@@ -1162,6 +1200,7 @@ test_secret_specs_for_harness_maps_opencode_only
 test_create_task_passes_fireworks_env_for_opencode
 test_create_task_omits_env_for_non_opencode_harness
 test_create_task_fails_when_secret_fetch_fails
+test_create_task_failure_output_redacts_fetched_secret
 test_fetch_secret_fails_when_aws_missing
 test_target_ready_fails_when_target_absent
 test_target_ready_checks_expected_label

From f737cd82acd48428910650818f9226e8826273e5 Mon Sep 17 00:00:00 2001
From: Kadriya Bazarova <Kadriya89@users.noreply.github.com>
Date: Wed, 8 Jul 2026 13:21:31 -0500
Subject: [PATCH 3/9] no-mistakes(document): docs: cross-reference cmux
 provider-credential env passthrough

---
 docs/configuration.md | 3 ++-
 docs/scripts.md       | 2 +-
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/configuration.md b/docs/configuration.md
index 8256048c9..3a89ddc2a 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -55,7 +55,8 @@ Today that probe can classify tmux and herdr secondmate endpoints as `alive`, `d
 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 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.
+A cmux spawn whose harness needs an injected provider credential (today only `opencode` -> `FIREWORKS_API_KEY`) also fetches that secret from AWS Secrets Manager and refuses loudly when the fetch fails; see [`docs/cmux-backend.md`](cmux-backend.md) "Provider credential passthrough (`--env`)".
+A backend spawn refusal from a missing dependency, version gate, unauthenticated socket, or failed credential fetch 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.
 A herdr task additionally records `herdr_session=`, `herdr_workspace_id=`, `herdr_tab_id=`, and `herdr_pane_id=`.
 A zellij task additionally records `zellij_session=`, `zellij_tab_id=`, and `zellij_pane_id=`.
diff --git a/docs/scripts.md b/docs/scripts.md
index b346d73ff..78c2417c4 100644
--- a/docs/scripts.md
+++ b/docs/scripts.md
@@ -35,7 +35,7 @@ The shared no-mistakes gate refusal used by `fm-spawn.sh`, `fm-send.sh`, and `fm
 | `backends/herdr.sh`      | Experimental herdr session-provider adapter                                          |
 | `backends/zellij.sh`     | Experimental zellij session-provider adapter                                         |
 | `backends/orca.sh`       | Experimental Orca backend adapter owning both worktree and terminal                  |
-| `backends/cmux.sh`       | Experimental cmux session-provider adapter                                           |
+| `backends/cmux.sh`       | Experimental cmux session-provider adapter with per-harness provider-credential `--env` passthrough ([cmux-backend.md](cmux-backend.md#provider-credential-passthrough---env)) |
 | `fm-config-push.sh`      | Push declared inheritable local config to live secondmate homes mid-session          |
 | `fm-project-mode.sh`     | Resolve a project's delivery mode and `+yolo` flag from `data/projects.md`           |
 | `fm-merge-local.sh`      | Fast-forward a `local-only` project's local default branch after approval            |

From b5d472322e9f359beaee22ad6d2e577555e9bc18 Mon Sep 17 00:00:00 2001
From: Kadriya Bazarova <Kadriya89@users.noreply.github.com>
Date: Wed, 8 Jul 2026 14:07:43 -0500
Subject: [PATCH 4/9] no-mistakes(review): cmux env secrets via local config;
 surface AWS stderr

---
 .gitignore                    |   1 +
 bin/backends/cmux.sh          |  94 ++++++++++++++++---------
 docs/cmux-backend.md          |  11 +--
 docs/configuration.md         |   5 +-
 tests/fm-backend-cmux.test.sh | 125 +++++++++++++++++++++++++---------
 5 files changed, 166 insertions(+), 70 deletions(-)

diff --git a/.gitignore b/.gitignore
index 5ed2da0c3..6e9565557 100644
--- a/.gitignore
+++ b/.gitignore
@@ -15,4 +15,5 @@ config/backlog-backend
 config/backend
 config/x-mode.env
 config/cmux-socket-password
+config/cmux-env-secrets
 config/wedge-alarm
diff --git a/bin/backends/cmux.sh b/bin/backends/cmux.sh
index 075d0687a..cb318e2c3 100644
--- a/bin/backends/cmux.sh
+++ b/bin/backends/cmux.sh
@@ -341,34 +341,62 @@ fm_backend_cmux_surface_id_for_workspace() {  # <workspace_id>
     | jq -r '.panes[0] // {} | .selected_surface_id // (.surface_ids[0] // empty)' 2>/dev/null
 }
 
-# fm_backend_cmux_secret_specs_for_harness: zero or more "ENV_VAR
-# secret-name" lines naming the provider credentials that must be explicitly
-# injected into a cmux workspace for <harness>. Needed only for cmux: unlike
-# tmux/herdr/zellij (which fork a task inside the same host shell and so
-# inherit firstmate's own process environment), a cmux terminal surface's
-# environment is heavily scrubbed at spawn time (docs/cmux-backend.md
-# "Provider credential passthrough (--env)") - ambient provider API keys
-# never reach it. One pairing exists today: opencode's Fireworks-backed
-# models (e.g. GLM 5.2) need FIREWORKS_API_KEY. Expressed as a lookup table
-# so a second pairing is a one-line addition rather than a new framework.
+# fm_backend_cmux_secret_specs_for_harness: zero or more "ENV_VAR secret-name
+# [region]" lines naming the provider credentials that must be explicitly
+# injected into a cmux workspace for <harness>, read fresh from the local,
+# gitignored config/cmux-env-secrets under the effective config dir (the same
+# read-fresh convention as fm_backend_cmux_password above). Each config line
+# is "<harness> <ENV_VAR> <secret-name> [<aws-region>]"; blank lines and
+# '#'-prefixed lines are ignored (docs/cmux-backend.md "Provider credential
+# passthrough (--env)"). Needed only for cmux: unlike tmux/herdr/zellij
+# (which fork a task inside the same host shell and so inherit firstmate's
+# own process environment), a cmux terminal surface's environment is heavily
+# scrubbed at spawn time - ambient provider API keys never reach it. An
+# absent file, or a harness with no matching line, means no injection at all.
 fm_backend_cmux_secret_specs_for_harness() {  # <harness>
-  case "$1" in
-    opencode) printf 'FIREWORKS_API_KEY opencode/fireworks-api-key\n' ;;
-  esac
+  local harness=$1 config_dir="${FM_CONFIG_OVERRIDE:-$FM_HOME/config}" f h env_var secret_name region _rest
+  f="$config_dir/cmux-env-secrets"
+  [ -f "$f" ] || return 0
+  while read -r h env_var secret_name region _rest || [ -n "$h" ]; do
+    case "$h" in ''|'#'*) continue ;; esac
+    [ "$h" = "$harness" ] || continue
+    [ -n "$secret_name" ] || continue
+    if [ -n "$region" ]; then
+      printf '%s %s %s\n' "$env_var" "$secret_name" "$region"
+    else
+      printf '%s %s\n' "$env_var" "$secret_name"
+    fi
+  done < "$f"
 }
 
 # fm_backend_cmux_fetch_secret: print <secret-name>'s current value from AWS
-# Secrets Manager (region us-east-1) on stdout, using whatever AWS
-# credentials/profile are already ambient in this process's environment -
-# never a hardcoded profile. Fails loudly rather than continuing without the
-# key: a missing 'aws' CLI, a failed call (including no credentials
-# configured), or an empty secret are all refused.
-fm_backend_cmux_fetch_secret() {  # <secret-name>
-  local secret_name=$1 value
+# Secrets Manager on stdout (in [region] when given, otherwise whatever
+# region is ambient in AWS config), using whatever AWS credentials/profile
+# are already ambient in this process's environment - never a hardcoded
+# profile. Fails loudly rather than continuing without the key: a missing
+# 'aws' CLI, a failed call (whose AWS stderr is included in the error - AWS
+# error text never contains the secret value), or an empty secret are all
+# refused.
+fm_backend_cmux_fetch_secret() {  # <secret-name> [region]
+  local secret_name=$1 region=${2:-} where value err_file aws_err status=0
+  where="AWS Secrets Manager${region:+ (region $region)}"
   command -v aws >/dev/null 2>&1 || { echo "error: cmux env passthrough needs secret '$secret_name' but the 'aws' CLI is not installed" >&2; return 1; }
-  value=$(aws secretsmanager get-secret-value --secret-id "$secret_name" --region us-east-1 --query SecretString --output text 2>/dev/null) \
-    || { echo "error: failed to fetch secret '$secret_name' from AWS Secrets Manager (region us-east-1) - check that AWS credentials/profile are configured" >&2; return 1; }
-  [ -n "$value" ] && [ "$value" != None ] || { echo "error: secret '$secret_name' from AWS Secrets Manager returned an empty value" >&2; return 1; }
+  err_file=$(mktemp "${TMPDIR:-/tmp}/fm-cmux-aws-err.XXXXXX") || err_file=/dev/null
+  if [ -n "$region" ]; then
+    value=$(aws secretsmanager get-secret-value --secret-id "$secret_name" --region "$region" --query SecretString --output text 2>"$err_file") || status=$?
+  else
+    value=$(aws secretsmanager get-secret-value --secret-id "$secret_name" --query SecretString --output text 2>"$err_file") || status=$?
+  fi
+  aws_err=
+  if [ "$err_file" != /dev/null ]; then
+    aws_err=$(cat "$err_file" 2>/dev/null)
+    rm -f "$err_file"
+  fi
+  if [ "$status" -ne 0 ]; then
+    echo "error: failed to fetch secret '$secret_name' from $where - ${aws_err:-check that AWS credentials/profile are configured}" >&2
+    return 1
+  fi
+  [ -n "$value" ] && [ "$value" != None ] || { echo "error: secret '$secret_name' from $where returned an empty value" >&2; return 1; }
   printf '%s' "$value"
 }
 
@@ -381,12 +409,11 @@ fm_backend_cmux_fetch_secret() {  # <secret-name>
 # password. Empty array (success) when the harness needs no injected secret.
 fm_backend_cmux_env_args_for_harness() {  # <harness>
   FM_BACKEND_CMUX_ENV_ARGS=()
-  local harness=$1 spec env_var secret_name value
-  while IFS= read -r spec; do
-    [ -n "$spec" ] || continue
-    env_var=${spec%% *}
-    secret_name=${spec#* }
-    value=$(fm_backend_cmux_fetch_secret "$secret_name") || return 1
+  local harness=$1 env_var secret_name region value
+  [ -n "$harness" ] || return 0
+  while read -r env_var secret_name region; do
+    [ -n "$secret_name" ] || continue
+    value=$(fm_backend_cmux_fetch_secret "$secret_name" "$region") || return 1
     FM_BACKEND_CMUX_ENV_ARGS+=(--env "$env_var=$value")
   done < <(fm_backend_cmux_secret_specs_for_harness "$harness")
   return 0
@@ -400,10 +427,11 @@ fm_backend_cmux_env_args_for_harness() {  # <harness>
 # defense in depth though verified to already be the default (finding:
 # workspace/surface/pane create all default focus to false) - no
 # focus-restore dance is needed, unlike zellij. When <harness> is given and
-# needs provider credentials (fm_backend_cmux_secret_specs_for_harness), they
-# are fetched and passed as `--env KEY=VALUE` (verified flag: cmux-control's
-# own bin/cmuxctl, cmuxNewWorkspace). Echoes "<workspace_id> <surface_id>" on
-# success.
+# config/cmux-env-secrets pairs it with provider credentials
+# (fm_backend_cmux_secret_specs_for_harness), they are fetched and passed as
+# `--env KEY=VALUE` (verified flag: cmux-control's own bin/cmuxctl,
+# cmuxNewWorkspace); with no pairing configured, nothing is fetched or
+# injected. Echoes "<workspace_id> <surface_id>" on success.
 fm_backend_cmux_create_task() {  # <label> <cwd> [harness]
   local label=$1 cwd=$2 harness=${3:-} title dup out wsid sfid
   title=$(fm_backend_cmux_scoped_title "$label")
diff --git a/docs/cmux-backend.md b/docs/cmux-backend.md
index c97ade4e6..ccdd3dd72 100644
--- a/docs/cmux-backend.md
+++ b/docs/cmux-backend.md
@@ -332,11 +332,14 @@ Verified live: two workspaces created with the identical title `fm-test-dup` bot
 A cmux workspace's terminal surface starts with none of firstmate's own process environment worth relying on for provider credentials - unlike tmux/herdr/zellij, which fork a task inside the same host shell and so inherit it, a cmux surface is a fresh GUI-app-spawned process (see the wrapper-stripping finding above for a related, but distinct, case: that one is about the RUNTIME firstmate's own launch environment when firstmate itself runs inside a cmux tab; this one is about the environment of a workspace firstmate just CREATED for a task).
 So an ambient `FIREWORKS_API_KEY` set in firstmate's own shell never reaches a spawned opencode surface, and opencode's Fireworks-backed models (e.g. GLM 5.2) fail outright.
 
-`fm_backend_cmux_create_task` takes an optional third `<harness>` argument and, when that harness needs a provider credential (`fm_backend_cmux_secret_specs_for_harness` - one pairing today, `opencode` -> `FIREWORKS_API_KEY`), fetches it from AWS Secrets Manager (`opencode/fireworks-api-key`, region `us-east-1`, using whatever AWS credentials/profile are already ambient - never a hardcoded profile) and passes it to `new-workspace` as `--env FIREWORKS_API_KEY=<value>`.
+`fm_backend_cmux_create_task` takes an optional third `<harness>` argument and, when the local, gitignored `config/cmux-env-secrets` pairs that harness with one or more provider credentials (`fm_backend_cmux_secret_specs_for_harness`, which reads the file fresh from the effective config dir the same way `config/cmux-socket-password` is read), fetches each from AWS Secrets Manager (using whatever AWS credentials/profile are already ambient - never a hardcoded profile) and passes it to `new-workspace` as `--env KEY=<value>`.
+Each `config/cmux-env-secrets` line is `<harness> <ENV_VAR> <secret-name> [<aws-region>]`, with blank lines and `#`-prefixed lines ignored; an omitted region defers to ambient AWS region config.
+For example, `opencode FIREWORKS_API_KEY opencode/fireworks-api-key us-east-1` injects the Fireworks key an opencode spawn needs for its Fireworks-backed models (e.g. GLM 5.2).
+An absent file, or a harness with no matching line, injects nothing and triggers no AWS call at all - the spawn proceeds exactly as it did before this knob existed.
 `--env KEY=VALUE` is cmux-control's own verified mechanism for this (`bin/cmuxctl`'s `cmuxNewWorkspace`, which builds one `--env` pair per entry of an `env` object): a real, working `new-workspace` flag firstmate's own adapter simply never used before.
-A failed fetch (missing `aws` CLI, no credentials configured, an empty secret) fails the spawn loudly rather than silently launching opencode without the key it needs.
-The fetched value only ever lands in a shell variable used to build the `--env` argument - never printed, logged, or written to a file - the same convention `fm_backend_cmux_password`/`CMUX_SOCKET_PASSWORD` above already follows for the socket password.
-`bin/fm-spawn.sh` passes the resolved `$HARNESS` through on every cmux spawn; a harness with no configured secret spec (everything except opencode today) triggers no AWS call at all.
+A failed fetch (missing `aws` CLI, a failed call - whose AWS stderr is included in the spawn-failure error, since AWS error text never contains the secret value - or an empty secret) fails the spawn loudly rather than silently launching the harness without a key it was configured to need.
+The fetched value only ever lands in a shell variable used to build the `--env` argument - never printed, logged, or written to a file, and redacted from any echoed-back `new-workspace` failure output - the same convention `fm_backend_cmux_password`/`CMUX_SOCKET_PASSWORD` above already follows for the socket password.
+`bin/fm-spawn.sh` passes the resolved `$HARNESS` through on every cmux spawn.
 
 ## Composer verification: structural border-row classification (adapted from herdr)
 
diff --git a/docs/configuration.md b/docs/configuration.md
index 3a89ddc2a..076dfa25e 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -55,7 +55,7 @@ Today that probe can classify tmux and herdr secondmate endpoints as `alive`, `d
 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 spawn whose harness needs an injected provider credential (today only `opencode` -> `FIREWORKS_API_KEY`) also fetches that secret from AWS Secrets Manager and refuses loudly when the fetch fails; see [`docs/cmux-backend.md`](cmux-backend.md) "Provider credential passthrough (`--env`)".
+A cmux spawn whose harness has a provider-credential pairing configured in local, gitignored `config/cmux-env-secrets` also fetches that secret from AWS Secrets Manager and refuses loudly when the fetch fails; with no pairing configured, nothing is fetched or injected and the spawn proceeds as before - see [`docs/cmux-backend.md`](cmux-backend.md) "Provider credential passthrough (`--env`)".
 A backend spawn refusal from a missing dependency, version gate, unauthenticated socket, or failed credential fetch 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.
 A herdr task additionally records `herdr_session=`, `herdr_workspace_id=`, `herdr_tab_id=`, and `herdr_pane_id=`.
@@ -77,6 +77,7 @@ For normal zellij operations, `FM_ZELLIJ_SESSION` selects the named session and
 Zellij has no per-home workspace split: primary and secondmate tasks share that one session, and visible tab titles are scoped by the active `FM_HOME` readable label plus a short hash of the resolved `FM_ROOT` path as `fm-<home-label>-<id>`.
 Use the guarded cleanup path described in [`docs/zellij-backend.md`](zellij-backend.md) instead of `kill-all-sessions` or `delete-all-sessions`.
 cmux has no session layer at all - one workspace per task, in whatever cmux window is open - and its socket password (when configured) is read from local, gitignored `config/cmux-socket-password` under the effective config directory, never committed.
+Per-harness provider-credential injection for cmux workspaces is configured the same way in local, gitignored `config/cmux-env-secrets`: one `<harness> <ENV_VAR> <secret-name> [<aws-region>]` pairing per line (blank lines and `#`-prefixed lines ignored; an omitted region defers to ambient AWS region config), e.g. `opencode FIREWORKS_API_KEY opencode/fireworks-api-key us-east-1`.
 The caller-facing label remains `fm-<id>`, but the actual cmux workspace title is scoped by the active `FM_HOME` readable label plus a short hash of the resolved `FM_ROOT` path as `fm-<home-label>-<id>`.
 Test cleanup must use the guarded path described in [`docs/cmux-backend.md`](cmux-backend.md)'s "Test safety" section, never enumerate-and-close every workspace.
 The `config/backend` file is not inherited by secondmate homes.
@@ -152,7 +153,7 @@ When `FM_HOME` is unset, it also behaves as the old whole-root override.
 For the herdr backend, `FM_HOME` also determines the workspace label used by the adapter.
 For the zellij backend, `FM_HOME` does not split containers, but it determines the readable home prefix embedded in visible tab titles; use `FM_ZELLIJ_SESSION` when a separate zellij session is needed.
 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.
+For the cmux backend, `FM_CONFIG_OVERRIDE` overrides where `config/cmux-socket-password` and `config/cmux-env-secrets` are 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.
 
 ## Harness support
diff --git a/tests/fm-backend-cmux.test.sh b/tests/fm-backend-cmux.test.sh
index 7fdb0f1de..97207b856 100755
--- a/tests/fm-backend-cmux.test.sh
+++ b/tests/fm-backend-cmux.test.sh
@@ -69,8 +69,9 @@ SH
 # one already holding a fake `cmux` from make_cmux_fakebin), so opencode
 # create_task tests can fake both tools from one PATH entry. Logs every
 # invocation (one line, unit-separated args) to $FM_AWS_LOG and either exits
-# $FM_AWS_FAKE_EXIT (default 0) or prints $FM_AWS_FAKE_SECRET (default
-# 'fake-fireworks-key') on stdout, mirroring make_cmux_fakebin's
+# $FM_AWS_FAKE_EXIT (default 0) after printing $FM_AWS_FAKE_STDERR (default
+# an AccessDenied-shaped diagnostic) to stderr, or prints $FM_AWS_FAKE_SECRET
+# (default 'fake-fireworks-key') on stdout, mirroring make_cmux_fakebin's
 # log-and-canned-response convention. Never a real network call.
 add_fake_aws() {  # <fakebin-dir>
   local fb=$1
@@ -84,12 +85,31 @@ LOG="${FM_AWS_LOG:?}"
   printf '\n'
 } >> "$LOG"
 exit_code=${FM_AWS_FAKE_EXIT:-0}
-[ "$exit_code" -eq 0 ] || exit "$exit_code"
+if [ "$exit_code" -ne 0 ]; then
+  printf '%s\n' "${FM_AWS_FAKE_STDERR:-An error occurred (AccessDeniedException) when calling the GetSecretValue operation}" >&2
+  exit "$exit_code"
+fi
 printf '%s' "${FM_AWS_FAKE_SECRET:-fake-fireworks-key}"
 SH
   chmod +x "$fb/aws"
 }
 
+# write_cmux_env_secrets: write a config/cmux-env-secrets under <dir>/config
+# pairing opencode with the Fireworks secret (the motivating pairing,
+# docs/cmux-backend.md "Provider credential passthrough (--env)"), plus a
+# comment and blank line to exercise the parser, and echo the config dir for
+# use as FM_CONFIG_OVERRIDE. The adapter itself ships no hardcoded pairing.
+write_cmux_env_secrets() {  # <dir> -> echoes config dir
+  local cfg="$1/config"
+  mkdir -p "$cfg"
+  {
+    printf '# provider credentials injected into cmux workspaces at spawn\n'
+    printf '\n'
+    printf 'opencode FIREWORKS_API_KEY opencode/fireworks-api-key us-east-1\n'
+  } > "$cfg/cmux-env-secrets"
+  printf '%s\n' "$cfg"
+}
+
 cmux_workspace_list_response() {  # <dir> <n> <id1> <title1> [<id2> <title2> ...]
   local dir=$1 n=$2 json first=1
   shift 2
@@ -521,27 +541,38 @@ test_create_task_creates_and_parses_ids() {
   pass "fm_backend_cmux_create_task: creates a workspace and parses workspace_id/surface_id from list responses"
 }
 
-# --- create_task: opencode Fireworks env passthrough (--env) -----------------
+# --- create_task: provider-credential env passthrough (--env) ----------------
 #
 # cmux workspaces get none of firstmate's own process environment (heavily
-# scrubbed at spawn time, docs/cmux-backend.md "Environment scrubbing"), so an
-# opencode spawn needs FIREWORKS_API_KEY injected explicitly via `new-workspace
-# --env KEY=VALUE`. These tests fake both `cmux` and `aws` (add_fake_aws) so no
-# real AWS call is ever made.
-
-test_secret_specs_for_harness_maps_opencode_only() {
+# scrubbed at spawn time, docs/cmux-backend.md "Environment scrubbing"), so a
+# harness paired with a provider credential in the local, gitignored
+# config/cmux-env-secrets (e.g. opencode -> FIREWORKS_API_KEY) needs it
+# injected explicitly via `new-workspace --env KEY=VALUE`. These tests
+# configure the pairing via write_cmux_env_secrets/FM_CONFIG_OVERRIDE and fake
+# both `cmux` and `aws` (add_fake_aws) so no real AWS call is ever made.
+
+test_secret_specs_read_from_local_config() {
+  local dir cfg
+  dir="$TMP_ROOT/secret-specs-config"; mkdir -p "$dir"
+  cfg=$(write_cmux_env_secrets "$dir")
+  printf 'codex OPENAI_API_KEY codex/openai-api-key\n' >> "$cfg/cmux-env-secrets"
   ( . "$ROOT/bin/backends/cmux.sh"
-    out=$(fm_backend_cmux_secret_specs_for_harness opencode)
-    [ "$out" = "FIREWORKS_API_KEY opencode/fireworks-api-key" ] || { echo "opencode spec mismatch: '$out'" >&2; exit 1; }
-    out=$(fm_backend_cmux_secret_specs_for_harness claude)
-    [ -z "$out" ] || { echo "claude should need no injected secret, got '$out'" >&2; exit 1; }
-  ) || fail "fm_backend_cmux_secret_specs_for_harness did not map exactly opencode -> FIREWORKS_API_KEY/opencode/fireworks-api-key"
-  pass "fm_backend_cmux_secret_specs_for_harness: maps opencode to FIREWORKS_API_KEY/opencode/fireworks-api-key and other harnesses to nothing"
+    out=$(FM_CONFIG_OVERRIDE="$dir/nonexistent-config" fm_backend_cmux_secret_specs_for_harness opencode)
+    [ -z "$out" ] || { echo "an absent config file should configure no injection, got '$out'" >&2; exit 1; }
+    out=$(FM_CONFIG_OVERRIDE="$cfg" fm_backend_cmux_secret_specs_for_harness opencode)
+    [ "$out" = "FIREWORKS_API_KEY opencode/fireworks-api-key us-east-1" ] || { echo "opencode spec mismatch: '$out'" >&2; exit 1; }
+    out=$(FM_CONFIG_OVERRIDE="$cfg" fm_backend_cmux_secret_specs_for_harness codex)
+    [ "$out" = "OPENAI_API_KEY codex/openai-api-key" ] || { echo "region-less spec mismatch: '$out'" >&2; exit 1; }
+    out=$(FM_CONFIG_OVERRIDE="$cfg" fm_backend_cmux_secret_specs_for_harness claude)
+    [ -z "$out" ] || { echo "an unpaired harness should need no injected secret, got '$out'" >&2; exit 1; }
+  ) || fail "fm_backend_cmux_secret_specs_for_harness did not read pairings from config/cmux-env-secrets"
+  pass "fm_backend_cmux_secret_specs_for_harness: reads pairings (with optional region) from local config/cmux-env-secrets, skipping comments, blanks, unpaired harnesses, and an absent file"
 }
 
 test_create_task_passes_fireworks_env_for_opencode() {
-  local dir fb out title
+  local dir fb cfg out title
   dir="$TMP_ROOT/create-task-opencode-env"; mkdir -p "$dir/responses"
+  cfg=$(write_cmux_env_secrets "$dir")
   title=$(cmux_expected_scoped_title fm-oc1)
   # 1: workspace list --json (pre-create duplicate check) -> no match
   printf '{"workspaces":[]}' > "$dir/responses/1.out"
@@ -553,7 +584,7 @@ test_create_task_passes_fireworks_env_for_opencode() {
   fb=$(make_cmux_fakebin "$dir")
   add_fake_aws "$fb"
   out=$( PATH="$fb:$PATH" FM_CMUX_LOG="$dir/log" FM_CMUX_RESPONSES="$dir/responses" \
-    FM_AWS_LOG="$dir/aws-log" FM_AWS_FAKE_SECRET="s3cr3t-fireworks-key" \
+    FM_CONFIG_OVERRIDE="$cfg" FM_AWS_LOG="$dir/aws-log" FM_AWS_FAKE_SECRET="s3cr3t-fireworks-key" \
     bash -c '. "$0/bin/backends/cmux.sh"; fm_backend_cmux_create_task fm-oc1 /tmp/proj opencode' "$ROOT" )
   [ "$out" = "bbbbbbbb-1111-1111-1111-111111111111 cccccccc-2222-2222-2222-222222222222" ] \
     || fail "create_task should still echo '<workspace_id> <surface_id>' (never the secret) for an env-injected opencode spawn, got '$out'"
@@ -564,12 +595,13 @@ test_create_task_passes_fireworks_env_for_opencode() {
     "create_task did not fetch the Fireworks key from the documented Secrets Manager secret/region"
   assert_not_contains "$(cat "$dir/aws-log")" "profile" \
     "create_task's secret fetch should not hardcode an AWS profile"
-  pass "fm_backend_cmux_create_task: passes --env FIREWORKS_API_KEY=<value> to new-workspace for an opencode spawn"
+  pass "fm_backend_cmux_create_task: passes --env FIREWORKS_API_KEY=<value> to new-workspace for a config-paired opencode spawn"
 }
 
-test_create_task_omits_env_for_non_opencode_harness() {
-  local dir fb out title
+test_create_task_omits_env_for_unpaired_harness() {
+  local dir fb cfg out title
   dir="$TMP_ROOT/create-task-claude-no-env"; mkdir -p "$dir/responses"
+  cfg=$(write_cmux_env_secrets "$dir")
   title=$(cmux_expected_scoped_title fm-cl1)
   printf '{"workspaces":[]}' > "$dir/responses/1.out"
   cmux_workspace_list_response "$dir" 3 "bbbbbbbb-1111-1111-1111-111111111111" "$title"
@@ -577,40 +609,70 @@ test_create_task_omits_env_for_non_opencode_harness() {
   fb=$(make_cmux_fakebin "$dir")
   cat > "$fb/aws" <<'SH'
 #!/usr/bin/env bash
-echo "aws should not be invoked for a harness that needs no injected secret" >&2
+echo "aws should not be invoked for a harness with no configured pairing" >&2
 exit 1
 SH
   chmod +x "$fb/aws"
   out=$( PATH="$fb:$PATH" FM_CMUX_LOG="$dir/log" FM_CMUX_RESPONSES="$dir/responses" \
+    FM_CONFIG_OVERRIDE="$cfg" \
     bash -c '. "$0/bin/backends/cmux.sh"; fm_backend_cmux_create_task fm-cl1 /tmp/proj claude' "$ROOT" )
   [ "$out" = "bbbbbbbb-1111-1111-1111-111111111111 cccccccc-2222-2222-2222-222222222222" ] \
-    || fail "create_task should still succeed for a harness that needs no injected secret"
+    || fail "create_task should still succeed for a harness with no configured pairing"
   assert_not_contains "$(cat "$dir/log")" $'\x1f''--env' \
     "create_task should not pass --env for a harness with no configured secret spec"
-  pass "fm_backend_cmux_create_task: passes no --env flags, and never calls aws, for a harness with no configured secret (e.g. claude)"
+  pass "fm_backend_cmux_create_task: passes no --env flags, and never calls aws, for a harness config/cmux-env-secrets does not pair (e.g. claude)"
+}
+
+test_create_task_skips_env_when_unconfigured() {
+  local dir fb out title
+  dir="$TMP_ROOT/create-task-no-config"; mkdir -p "$dir/responses"
+  title=$(cmux_expected_scoped_title fm-oc-nocfg)
+  printf '{"workspaces":[]}' > "$dir/responses/1.out"
+  cmux_workspace_list_response "$dir" 3 "bbbbbbbb-1111-1111-1111-111111111111" "$title"
+  cmux_panes_response "$dir" 4 "cccccccc-2222-2222-2222-222222222222"
+  fb=$(make_cmux_fakebin "$dir")
+  cat > "$fb/aws" <<'SH'
+#!/usr/bin/env bash
+echo "aws should not be invoked when config/cmux-env-secrets is absent" >&2
+exit 1
+SH
+  chmod +x "$fb/aws"
+  out=$( PATH="$fb:$PATH" FM_CMUX_LOG="$dir/log" FM_CMUX_RESPONSES="$dir/responses" \
+    FM_CONFIG_OVERRIDE="$dir/no-such-config" \
+    bash -c '. "$0/bin/backends/cmux.sh"; fm_backend_cmux_create_task fm-oc-nocfg /tmp/proj opencode' "$ROOT" )
+  [ "$out" = "bbbbbbbb-1111-1111-1111-111111111111 cccccccc-2222-2222-2222-222222222222" ] \
+    || fail "create_task should spawn exactly as before when no config/cmux-env-secrets exists, got '$out'"
+  assert_not_contains "$(cat "$dir/log")" $'\x1f''--env' \
+    "create_task should not pass --env when no pairing is configured at all"
+  pass "fm_backend_cmux_create_task: with no config/cmux-env-secrets, injects nothing and never calls aws - the spawn proceeds as before the knob existed"
 }
 
 test_create_task_fails_when_secret_fetch_fails() {
-  local dir fb out status
+  local dir fb cfg out status
   dir="$TMP_ROOT/create-task-secret-fail"; mkdir -p "$dir/responses"
+  cfg=$(write_cmux_env_secrets "$dir")
   # 1: workspace list --json (pre-create duplicate check) -> no match
   printf '{"workspaces":[]}' > "$dir/responses/1.out"
   fb=$(make_cmux_fakebin "$dir")
   add_fake_aws "$fb"
   out=$( PATH="$fb:$PATH" FM_CMUX_LOG="$dir/log" FM_CMUX_RESPONSES="$dir/responses" \
-    FM_AWS_LOG="$dir/aws-log" FM_AWS_FAKE_EXIT=1 \
+    FM_CONFIG_OVERRIDE="$cfg" FM_AWS_LOG="$dir/aws-log" FM_AWS_FAKE_EXIT=1 \
+    FM_AWS_FAKE_STDERR="An error occurred (AccessDeniedException) when calling the GetSecretValue operation: not authorized" \
     bash -c '. "$0/bin/backends/cmux.sh"; fm_backend_cmux_create_task fm-oc-fail /tmp/proj opencode' "$ROOT" 2>&1 )
   status=$?
   [ "$status" -ne 0 ] || fail "create_task should fail when the Fireworks secret cannot be fetched, rather than spawning without it"
   assert_not_contains "$(cat "$dir/log")" $'\x1f''new-workspace' \
     "create_task should never call new-workspace when the required secret fetch failed"
   assert_contains "$out" "opencode/fireworks-api-key" "create_task's failure did not name the secret it could not fetch"
-  pass "fm_backend_cmux_create_task: fails before creating the workspace when the required secret cannot be fetched"
+  assert_contains "$out" "AccessDeniedException" \
+    "create_task's fetch-failure error should include the AWS CLI's own stderr diagnostics"
+  pass "fm_backend_cmux_create_task: fails before creating the workspace when the required secret cannot be fetched, surfacing the AWS CLI's stderr"
 }
 
 test_create_task_failure_output_redacts_fetched_secret() {
-  local dir fb out status
+  local dir fb cfg out status
   dir="$TMP_ROOT/create-task-secret-redact"; mkdir -p "$dir/responses"
+  cfg=$(write_cmux_env_secrets "$dir")
   fb=$(make_cmux_fakebin "$dir")
   add_fake_aws "$fb"
   # A `cmux` stub whose new-workspace fails with a usage-style error that
@@ -634,7 +696,7 @@ exit 0
 SH
   chmod +x "$fb/cmux"
   out=$( PATH="$fb:$PATH" FM_CMUX_LOG="$dir/log" FM_CMUX_RESPONSES="$dir/responses" \
-    FM_AWS_LOG="$dir/aws-log" FM_AWS_FAKE_SECRET="s3cr3t-fireworks-key" \
+    FM_CONFIG_OVERRIDE="$cfg" FM_AWS_LOG="$dir/aws-log" FM_AWS_FAKE_SECRET="s3cr3t-fireworks-key" \
     bash -c '. "$0/bin/backends/cmux.sh"; fm_backend_cmux_create_task fm-oc-redact /tmp/proj opencode' "$ROOT" 2>&1 )
   status=$?
   [ "$status" -ne 0 ] || fail "create_task should fail when new-workspace fails"
@@ -1196,9 +1258,10 @@ test_ensure_running_fails_fast_on_denied_without_launching
 test_ensure_running_fails_fast_on_unauth_without_launching
 test_create_task_refuses_duplicate_label
 test_create_task_creates_and_parses_ids
-test_secret_specs_for_harness_maps_opencode_only
+test_secret_specs_read_from_local_config
 test_create_task_passes_fireworks_env_for_opencode
-test_create_task_omits_env_for_non_opencode_harness
+test_create_task_omits_env_for_unpaired_harness
+test_create_task_skips_env_when_unconfigured
 test_create_task_fails_when_secret_fetch_fails
 test_create_task_failure_output_redacts_fetched_secret
 test_fetch_secret_fails_when_aws_missing

From 04fc506ab5f79cb5dccdbe77a05c9bb5fee027dd Mon Sep 17 00:00:00 2001
From: Kadriya Bazarova <Kadriya89@users.noreply.github.com>
Date: Wed, 8 Jul 2026 14:14:10 -0500
Subject: [PATCH 5/9] no-mistakes(review): warn on malformed cmux-env-secrets
 pairing lines

---
 bin/backends/cmux.sh          | 10 ++++++++--
 docs/cmux-backend.md          |  1 +
 docs/configuration.md         |  1 +
 tests/fm-backend-cmux.test.sh | 21 +++++++++++++++++++++
 4 files changed, 31 insertions(+), 2 deletions(-)

diff --git a/bin/backends/cmux.sh b/bin/backends/cmux.sh
index cb318e2c3..785ee92da 100644
--- a/bin/backends/cmux.sh
+++ b/bin/backends/cmux.sh
@@ -352,7 +352,10 @@ fm_backend_cmux_surface_id_for_workspace() {  # <workspace_id>
 # (which fork a task inside the same host shell and so inherit firstmate's
 # own process environment), a cmux terminal surface's environment is heavily
 # scrubbed at spawn time - ambient provider API keys never reach it. An
-# absent file, or a harness with no matching line, means no injection at all.
+# absent file, or a harness with no matching line, means no injection at all;
+# a harness-matching line missing its secret name is skipped with a stderr
+# warning so a mistyped pairing surfaces at spawn instead of silently
+# reverting to no injection.
 fm_backend_cmux_secret_specs_for_harness() {  # <harness>
   local harness=$1 config_dir="${FM_CONFIG_OVERRIDE:-$FM_HOME/config}" f h env_var secret_name region _rest
   f="$config_dir/cmux-env-secrets"
@@ -360,7 +363,10 @@ fm_backend_cmux_secret_specs_for_harness() {  # <harness>
   while read -r h env_var secret_name region _rest || [ -n "$h" ]; do
     case "$h" in ''|'#'*) continue ;; esac
     [ "$h" = "$harness" ] || continue
-    [ -n "$secret_name" ] || continue
+    if [ -z "$secret_name" ]; then
+      echo "warning: cmux env passthrough: ignoring malformed line in $f (missing secret name): $h${env_var:+ $env_var}" >&2
+      continue
+    fi
     if [ -n "$region" ]; then
       printf '%s %s %s\n' "$env_var" "$secret_name" "$region"
     else
diff --git a/docs/cmux-backend.md b/docs/cmux-backend.md
index ccdd3dd72..c2e8ab489 100644
--- a/docs/cmux-backend.md
+++ b/docs/cmux-backend.md
@@ -336,6 +336,7 @@ So an ambient `FIREWORKS_API_KEY` set in firstmate's own shell never reaches a s
 Each `config/cmux-env-secrets` line is `<harness> <ENV_VAR> <secret-name> [<aws-region>]`, with blank lines and `#`-prefixed lines ignored; an omitted region defers to ambient AWS region config.
 For example, `opencode FIREWORKS_API_KEY opencode/fireworks-api-key us-east-1` injects the Fireworks key an opencode spawn needs for its Fireworks-backed models (e.g. GLM 5.2).
 An absent file, or a harness with no matching line, injects nothing and triggers no AWS call at all - the spawn proceeds exactly as it did before this knob existed.
+A harness-matching line missing its `<secret-name>` field is malformed: it is skipped with a one-line stderr warning naming the file and offending line, so a mistyped pairing surfaces at spawn instead of silently reverting to no injection.
 `--env KEY=VALUE` is cmux-control's own verified mechanism for this (`bin/cmuxctl`'s `cmuxNewWorkspace`, which builds one `--env` pair per entry of an `env` object): a real, working `new-workspace` flag firstmate's own adapter simply never used before.
 A failed fetch (missing `aws` CLI, a failed call - whose AWS stderr is included in the spawn-failure error, since AWS error text never contains the secret value - or an empty secret) fails the spawn loudly rather than silently launching the harness without a key it was configured to need.
 The fetched value only ever lands in a shell variable used to build the `--env` argument - never printed, logged, or written to a file, and redacted from any echoed-back `new-workspace` failure output - the same convention `fm_backend_cmux_password`/`CMUX_SOCKET_PASSWORD` above already follows for the socket password.
diff --git a/docs/configuration.md b/docs/configuration.md
index 076dfa25e..ba3628c52 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -78,6 +78,7 @@ Zellij has no per-home workspace split: primary and secondmate tasks share that
 Use the guarded cleanup path described in [`docs/zellij-backend.md`](zellij-backend.md) instead of `kill-all-sessions` or `delete-all-sessions`.
 cmux has no session layer at all - one workspace per task, in whatever cmux window is open - and its socket password (when configured) is read from local, gitignored `config/cmux-socket-password` under the effective config directory, never committed.
 Per-harness provider-credential injection for cmux workspaces is configured the same way in local, gitignored `config/cmux-env-secrets`: one `<harness> <ENV_VAR> <secret-name> [<aws-region>]` pairing per line (blank lines and `#`-prefixed lines ignored; an omitted region defers to ambient AWS region config), e.g. `opencode FIREWORKS_API_KEY opencode/fireworks-api-key us-east-1`.
+A harness-matching pairing line missing its `<secret-name>` is skipped with a stderr warning at spawn rather than silently, per [`docs/cmux-backend.md`](cmux-backend.md) "Provider credential passthrough (`--env`)".
 The caller-facing label remains `fm-<id>`, but the actual cmux workspace title is scoped by the active `FM_HOME` readable label plus a short hash of the resolved `FM_ROOT` path as `fm-<home-label>-<id>`.
 Test cleanup must use the guarded path described in [`docs/cmux-backend.md`](cmux-backend.md)'s "Test safety" section, never enumerate-and-close every workspace.
 The `config/backend` file is not inherited by secondmate homes.
diff --git a/tests/fm-backend-cmux.test.sh b/tests/fm-backend-cmux.test.sh
index 97207b856..35a846b32 100755
--- a/tests/fm-backend-cmux.test.sh
+++ b/tests/fm-backend-cmux.test.sh
@@ -569,6 +569,26 @@ test_secret_specs_read_from_local_config() {
   pass "fm_backend_cmux_secret_specs_for_harness: reads pairings (with optional region) from local config/cmux-env-secrets, skipping comments, blanks, unpaired harnesses, and an absent file"
 }
 
+test_secret_specs_warns_on_malformed_matching_line() {
+  local dir cfg out warn
+  dir="$TMP_ROOT/secret-specs-malformed"; mkdir -p "$dir/config"
+  cfg="$dir/config"
+  printf 'opencode FIREWORKS_API_KEY\n' > "$cfg/cmux-env-secrets"
+  ( . "$ROOT/bin/backends/cmux.sh"
+    out=$(FM_CONFIG_OVERRIDE="$cfg" fm_backend_cmux_secret_specs_for_harness opencode 2>"$dir/warn.txt")
+    warn=$(cat "$dir/warn.txt")
+    [ -z "$out" ] || { echo "a malformed line must configure no injection, got '$out'" >&2; exit 1; }
+    case "$warn" in
+      *warning*"$cfg/cmux-env-secrets"*"opencode FIREWORKS_API_KEY"*) : ;;
+      *) echo "expected a stderr warning naming the file and offending line, got '$warn'" >&2; exit 1 ;;
+    esac
+    out=$(FM_CONFIG_OVERRIDE="$cfg" fm_backend_cmux_secret_specs_for_harness codex 2>"$dir/warn-other.txt")
+    warn=$(cat "$dir/warn-other.txt")
+    [ -z "$out" ] && [ -z "$warn" ] || { echo "a non-matching harness must stay silent, got out='$out' warn='$warn'" >&2; exit 1; }
+  ) || fail "fm_backend_cmux_secret_specs_for_harness did not warn on a harness-matching line missing its secret name"
+  pass "fm_backend_cmux_secret_specs_for_harness: warns loudly (file + offending line) when a harness-matching pairing lacks a secret name, instead of silently skipping it"
+}
+
 test_create_task_passes_fireworks_env_for_opencode() {
   local dir fb cfg out title
   dir="$TMP_ROOT/create-task-opencode-env"; mkdir -p "$dir/responses"
@@ -1259,6 +1279,7 @@ test_ensure_running_fails_fast_on_unauth_without_launching
 test_create_task_refuses_duplicate_label
 test_create_task_creates_and_parses_ids
 test_secret_specs_read_from_local_config
+test_secret_specs_warns_on_malformed_matching_line
 test_create_task_passes_fireworks_env_for_opencode
 test_create_task_omits_env_for_unpaired_harness
 test_create_task_skips_env_when_unconfigured

From dbf25a501123e5d6f2b153bbcc25dbeaaaf0b76d Mon Sep 17 00:00:00 2001
From: Kadriya Bazarova <Kadriya89@users.noreply.github.com>
Date: Wed, 8 Jul 2026 14:49:05 -0500
Subject: [PATCH 6/9] no-mistakes(document): sync cmux docs with
 provider-credential env passthrough

---
 docs/cmux-backend.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/docs/cmux-backend.md b/docs/cmux-backend.md
index c2e8ab489..229bb61ea 100644
--- a/docs/cmux-backend.md
+++ b/docs/cmux-backend.md
@@ -20,6 +20,7 @@ Prerequisites:
 - `jq`, required to parse cmux's JSON output: `brew install jq` (or your platform's package manager).
 - The universal firstmate prerequisites - a verified crew harness plus the required toolchain, owned by [`docs/configuration.md`](configuration.md) ("Harness support", "Toolchain"); treehouse still provides the worktree, cmux only provides the session.
 - The cmux CLI binary is not guaranteed to be on `PATH` after a plain app install (see "CLI is not on PATH by default" below) - the adapter falls back to the well-known bundle path automatically, so this is not a blocker, just something to be aware of if you want to run `cmux` yourself from a shell.
+- The `aws` CLI, only if you configure provider-credential passthrough via `config/cmux-env-secrets` (see "Provider credential passthrough (`--env`)" below) - with a pairing configured, a spawn that cannot fetch the secret refuses loudly; with no pairing, `aws` is not needed at all.
 
 **One-time socket access setup (required, not optional):** cmux's control socket defaults to `automation.socketControlMode: "cmuxOnly"`, which rejects any CLI process not spawned inside cmux itself - firstmate always drives cmux from an external shell, so this must be changed before `backend=cmux` can work at all.
 Settings > Automation offers five Socket Control Mode values; their exact semantics were verified from cmux source (see "Socket control modes: the full matrix" below for the enforcement points and evidence):
@@ -171,7 +172,7 @@ No session field is needed - unlike herdr/zellij there is no session layer to re
 | Version gate | `cmux version` -> `"cmux 0.64.17 (97) [9ed29d81a]"` | Works with NO socket connection at all - a pure client-version check, verified even while the socket was still rejecting connections. |
 | Reachability/auth gate | `cmux ping` -> `"PONG"` or a typed error | Classified into `ok`\|`denied`\|`unauth`\|`down`\|`error` from the error text (`fm_backend_cmux_ping_state`); `fm_backend_cmux_ensure_running` launches the app (`open -a cmux`) only for `down`, and fails fast with an actionable message for `denied`/`unauth` since relaunching cannot fix a configuration problem. |
 | Duplicate task check | `cmux workspace list --json --id-format uuids`, match by home-scoped `.title` | cmux enforces NO title uniqueness for workspaces OR surfaces/tabs - verified live: two workspaces, and two surfaces within one workspace, all created successfully sharing one title. The adapter's own duplicate check is required, mirroring herdr/zellij, and it checks the scoped title such as `fm-firstmate-<8hex>-<id>`. |
-| Create task workspace | `cmux new-workspace --name <scoped-title> --cwd <dir> --focus false --id-format uuids` | Creates a workspace with exactly one default surface. `--focus` verified to already default to `false` for workspace/surface/pane creation - no focus-restore dance needed, unlike zellij. The caller passes `fm-<id>`, but the adapter creates `fm-<home-label>-<id>`. |
+| Create task workspace | `cmux new-workspace --name <scoped-title> --cwd <dir> [--env KEY=<value> ...] --focus false --id-format uuids` | Creates a workspace with exactly one default surface. `--focus` verified to already default to `false` for workspace/surface/pane creation - no focus-restore dance needed, unlike zellij. The caller passes `fm-<id>`, but the adapter creates `fm-<home-label>-<id>`. The `--env` pairs appear only when `config/cmux-env-secrets` pairs the spawning harness with provider credentials (see "Provider credential passthrough (`--env`)" below; flag verified from cmux-control's own `bin/cmuxctl` source). |
 | Workspace/surface id resolution | `cmux workspace list --json --id-format uuids` (find by home-scoped title), then `cmux list-panes --workspace <id> --json --id-format uuids` (`.panes[0].selected_surface_id`) | A freshly created workspace already has exactly one surface, so no separate `new-surface` call is needed. `--id-format uuids` (or `both`) is required to get a bare `id` field in JSON; the default JSON shape returns only short `ref` strings like `"workspace:2"`. |
 | Liveness / target readiness | `cmux list-panes --workspace <id> --json --id-format uuids`, checking the surface id appears in `.panes[].surface_ids` | Structural existence check, NOT a content read - see "read-screen fails on a genuinely fresh surface" below for why `read-screen` cannot be used here. Verified reliable on a completely untouched fresh surface, unlike `read-screen`. |
 | Send literal (unsubmitted) | `cmux send --workspace <id> --surface <id> -- <text>` | Verified live: does NOT auto-submit - text sits at the prompt, unexecuted, until a separate Enter. Matches every other backend's "literal-then-separate-Enter" contract. The `--` separator keeps option-shaped text such as `--help` literal. |
@@ -385,5 +386,6 @@ All three tasks' cmux workspaces and worktrees were confirmed fully cleaned up a
   The one-time socket-access setup remains an unavoidable manual step regardless of how the backend was selected.
 - **`--secondmate` spawns are refused** (mirrors Orca's refusal) - no per-home container design (a herdr-style workspace-per-home split, or similar) has been designed or verified for cmux yet.
 - **The one-time socket-access setup is a real, undocumented-by-upstream onboarding step.** A captain who selects `backend=cmux` without first switching `automation.socketControlMode` away from its `cmuxOnly` default to a viable mode (Automation mode recommended; see "Setup") will see every spawn fail with an actionable error naming the viable modes and pointing back to this document, but there is no way for firstmate to complete that GUI-only setup step on the captain's behalf.
+- **`aws` is not bootstrap-detected** - `bin/fm-bootstrap.sh`'s backend-aware required-tool detection covers `cmux` and `jq` for a cmux backend selection, but does not add `aws` when `config/cmux-env-secrets` configures provider-credential passthrough; the credential fetch happens at spawn time instead and refuses loudly.
 - **A surface can still die in the brief window between `target_ready` succeeding and the operation's own call running.** That remaining race degrades to "the operation quietly did nothing" - the same class of gap firstmate already tolerates for an unverified send on any backend, caught downstream by `fm-spawn.sh`'s worktree-discovery poll timing out, `fm_backend_cmux_send_text_submit`'s retry loop (which reports `send-failed`/`pending`/`unknown` rather than a false "sent"), or the watcher's stale-pane detection.
 - **Windows cannot be closed over the control socket, and label lookup is current-window scoped** - both owned by "Closing the last workspace in a window" above. Teardown of a last-in-window task workspace therefore leaves that window a fresh default workspace rather than closing it, and `fm_backend_cmux_workspace_id_for_label`/`fm_backend_cmux_list_live` only see the current window, so a task workspace parked in a non-current window is a known blind spot for label-based recovery.

From cf341965a7b0e560eed21529995d347730711cb9 Mon Sep 17 00:00:00 2001
From: Kadriya Bazarova <Kadriya89@users.noreply.github.com>
Date: Mon, 13 Jul 2026 13:48:05 -0500
Subject: [PATCH 7/9] lint: rewrite SC2015 and-or chain as if/then in cmux
 secret fetch

---
 bin/backends/cmux.sh | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/bin/backends/cmux.sh b/bin/backends/cmux.sh
index 785ee92da..0f9bf1c7a 100644
--- a/bin/backends/cmux.sh
+++ b/bin/backends/cmux.sh
@@ -402,7 +402,10 @@ fm_backend_cmux_fetch_secret() {  # <secret-name> [region]
     echo "error: failed to fetch secret '$secret_name' from $where - ${aws_err:-check that AWS credentials/profile are configured}" >&2
     return 1
   fi
-  [ -n "$value" ] && [ "$value" != None ] || { echo "error: secret '$secret_name' from $where returned an empty value" >&2; return 1; }
+  if [ -z "$value" ] || [ "$value" = None ]; then
+    echo "error: secret '$secret_name' from $where returned an empty value" >&2
+    return 1
+  fi
   printf '%s' "$value"
 }
 

From 03b6138d8e01cb070c6039163c2a0d0cec79de11 Mon Sep 17 00:00:00 2001
From: Kadriya Bazarova <Kadriya89@users.noreply.github.com>
Date: Mon, 13 Jul 2026 14:34:09 -0500
Subject: [PATCH 8/9] no-mistakes(test): fix test fixtures: composer-lib
 symlink, tasks-axi skip, peer readiness

---
 tests/fm-backlog-handoff.test.sh          |  6 +++++-
 tests/fm-gotmp.test.sh                    |  1 +
 tests/fm-secondmate-lifecycle-e2e.test.sh |  9 ++++++++-
 tests/fm-watcher-lock.test.sh             | 15 +++++++++++++--
 4 files changed, 27 insertions(+), 4 deletions(-)

diff --git a/tests/fm-backlog-handoff.test.sh b/tests/fm-backlog-handoff.test.sh
index 9e10703e8..af147261c 100755
--- a/tests/fm-backlog-handoff.test.sh
+++ b/tests/fm-backlog-handoff.test.sh
@@ -10,8 +10,12 @@ set -u
 . "$(dirname "${BASH_SOURCE[0]}")/secondmate-helpers.sh"
 
 # The move is delegated to `tasks-axi mv`, so this suite exercises the real
-# binary. Skip cleanly when it is absent (matching the backend smoke suites).
+# binary. Skip cleanly when it is absent (matching the backend smoke suites) or
+# incompatible (the handoff path itself requires atomic multi-ID mv, 0.2.2+).
 command -v tasks-axi >/dev/null 2>&1 || { echo "skip: tasks-axi not found (required by the delegated handoff path)"; exit 0; }
+# shellcheck source=bin/fm-tasks-axi-lib.sh disable=SC1091
+. "$ROOT/bin/fm-tasks-axi-lib.sh"
+fm_tasks_axi_compatible || { echo "skip: tasks-axi lacks atomic multi-ID mv support (0.2.2+ required by the delegated handoff path)"; exit 0; }
 
 TMP_ROOT=$(fm_test_tmproot fm-backlog-handoff)
 
diff --git a/tests/fm-gotmp.test.sh b/tests/fm-gotmp.test.sh
index 03f0afafa..8a011996d 100755
--- a/tests/fm-gotmp.test.sh
+++ b/tests/fm-gotmp.test.sh
@@ -58,6 +58,7 @@ make_fake_root() {
   ln -s "$ROOT/bin/fm-backend.sh" "$fake/bin/fm-backend.sh"
   ln -s "$ROOT/bin/backends/tmux.sh" "$fake/bin/backends/tmux.sh"
   ln -s "$ROOT/bin/fm-tmux-lib.sh" "$fake/bin/fm-tmux-lib.sh"
+  # fm-composer-lib.sh: fm-tmux-lib.sh sources it as a sibling.
   ln -s "$ROOT/bin/fm-composer-lib.sh" "$fake/bin/fm-composer-lib.sh"
   # fm-lock-lib.sh: teardown sources it for the shared lock-staleness proof.
   ln -s "$ROOT/bin/fm-lock-lib.sh" "$fake/bin/fm-lock-lib.sh"
diff --git a/tests/fm-secondmate-lifecycle-e2e.test.sh b/tests/fm-secondmate-lifecycle-e2e.test.sh
index fd71fdb35..5fadb662a 100755
--- a/tests/fm-secondmate-lifecycle-e2e.test.sh
+++ b/tests/fm-secondmate-lifecycle-e2e.test.sh
@@ -151,12 +151,19 @@ phase_send() {
 }
 
 phase_handoff() {
-  # The move is delegated to `tasks-axi mv`; skip cleanly when it is absent (the
+  # The move is delegated to `tasks-axi mv`; skip cleanly when it is absent or
+  # incompatible - the handoff path requires atomic multi-ID mv, 0.2.2+ - (the
   # downstream recovery and teardown phases do not depend on this phase).
   if ! command -v tasks-axi >/dev/null 2>&1; then
     echo "skip: tasks-axi not found (backlog handoff delegates to it)"
     return 0
   fi
+  # shellcheck source=bin/fm-tasks-axi-lib.sh disable=SC1091
+  . "$ROOT/bin/fm-tasks-axi-lib.sh"
+  if ! fm_tasks_axi_compatible; then
+    echo "skip: tasks-axi lacks atomic multi-ID mv support (0.2.2+, required by the handoff path)"
+    return 0
+  fi
   cat > "$HOME_DIR/data/backlog.md" <<'EOF'
 ## In flight
 - [ ] live-task - active work (repo: alpha, since 2026-06-20)
diff --git a/tests/fm-watcher-lock.test.sh b/tests/fm-watcher-lock.test.sh
index 36e1f8dd4..ef81438a6 100755
--- a/tests/fm-watcher-lock.test.sh
+++ b/tests/fm-watcher-lock.test.sh
@@ -437,14 +437,25 @@ test_watch_restart_rejects_reused_pid() {
 }
 
 test_watch_restart_reports_healthy_peer_without_attaching() {
-  local dir state fakebin out peer identity armpid status
+  local dir state fakebin out peer identity armpid status ready i
   dir=$(make_case restart-healthy-peer)
   state="$dir/state"
   fakebin="$dir/fakebin"
   out="$dir/restart.out"
   mark_pr_check_migration_complete "$state"
-  node -e 'process.on("SIGTERM", () => {}); setTimeout(() => {}, 300000)' &
+  # The peer must already be TERM-resistant when the restart arm signals it, and
+  # node only registers the handler after interpreter startup - so have the peer
+  # signal readiness and wait for it, or the arm's TERM can land first and kill
+  # a handler-less peer (turning this into the started-a-fresh-watcher path).
+  ready="$dir/peer.ready"
+  node -e 'process.on("SIGTERM", () => {}); require("fs").writeFileSync(process.argv[1], "ready\n"); setTimeout(() => {}, 300000)' "$ready" &
   peer=$!
+  i=0
+  while [ "$i" -lt 50 ] && [ ! -s "$ready" ]; do
+    sleep 0.1
+    i=$((i + 1))
+  done
+  [ -s "$ready" ] || fail "peer never signaled SIGTERM-handler readiness"
   identity=$(FM_STATE_OVERRIDE="$state" bash -c '. "$1"; fm_pid_identity "$2"' _ "$LIB" "$peer") || fail "could not identify peer pid"
   mkdir "$state/.watch.lock"
   printf '%s\n' "$peer" > "$state/.watch.lock/pid"

From 94d64f2c9bca272e35cbb5a95f2df1d8ed9edf74 Mon Sep 17 00:00:00 2001
From: Kadriya Bazarova <Kadriya89@users.noreply.github.com>
Date: Mon, 13 Jul 2026 14:52:27 -0500
Subject: [PATCH 9/9] no-mistakes(document): sync spawn-refusal docs with cmux
 credential-fetch failure

---
 AGENTS.md       | 2 +-
 bin/fm-spawn.sh | 5 +++--
 2 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 90f9e796e..64a37bf1f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -159,7 +159,7 @@ Do not add model-specific versions of that policy.
 
 `secondmate-provisioning` owns secondmate harness pins and config inheritance, while `harness-adapters` owns the harness consequences.
 Dispatch only on a backend that `fm-spawn` validates as spawn-capable.
-A missing dependency, authentication failure, unsupported backend, or version refusal is a blocker; never silently retry on another backend.
+A missing dependency, authentication failure, unsupported backend, version refusal, or failed provider-credential fetch is a blocker; never silently retry on another backend.
 
 ## 5. Recovery
 
diff --git a/bin/fm-spawn.sh b/bin/fm-spawn.sh
index 989839090..0eaa96edd 100755
--- a/bin/fm-spawn.sh
+++ b/bin/fm-spawn.sh
@@ -25,8 +25,9 @@
 #   blocked backend contract. Default tmux spawns do not write backend= to meta;
 #   absent backend= means tmux. cmux does not support --secondmate spawns yet.
 #   A backend spawn refusal (missing dependency, version gate, unauthenticated
-#   socket, or unsupported secondmate mode) is terminal for that selected backend;
-#   callers must surface it instead of silently retrying another backend.
+#   socket, failed provider-credential fetch, or unsupported secondmate mode) is
+#   terminal for that selected backend; callers must surface it instead of
+#   silently retrying another backend.
 #   With no harness arg, a crewmate/scout spawn resolves the CREW harness only when
 #   config/crew-dispatch.json is absent. When that file exists, crewmate/scout
 #   spawns require an explicit harness so firstmate cannot silently skip dispatch