fix(fleet): resolve runtime PATH for durable detached agent launch

Derive a runtime-bin PATH prefix (MOSAIC_RUNTIME_BIN override, then
npm-prefix/bin, then ~/.npm-global/bin / ~/.local/bin) and bake it
into the tmux pane command as `export PATH="<prefix>:${PATH}"; exec
<cmd>` so the runtime binary (mosaic/pi/codex) is always found in a
login+non-interactive pane shell that does not source ~/.bashrc.
Using `exec` makes the runtime the pane foreground process, eliminating
the DRIFT false-positive in `mosaic fleet ps`.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RMoEx7hfdFGjUiCHuN1RRi

packages/mosaic/framework/tools/fleet/start-agent-session.sh

@@ -26,5 +26,74 @@ if [ -z "$MOSAIC_AGENT_COMMAND" ]; then
   MOSAIC_AGENT_COMMAND="mosaic yolo $MOSAIC_AGENT_RUNTIME"
 fi
 
+# ── Derive a runtime-bin PATH prefix ─────────────────────────────────────────
+# Precedence:
+#   1. $MOSAIC_RUNTIME_BIN (explicit override)
+#   2. $(npm config get prefix)/bin  (if npm is on PATH)
+#   3. Fallbacks: $HOME/.npm-global/bin and $HOME/.local/bin
+#
+# Only directories that already exist are included.  Directories already
+# present in PATH are skipped so we never duplicate entries.
+_build_runtime_bin_prefix() {
+  local candidates=()
+
+  if [ -n "${MOSAIC_RUNTIME_BIN:-}" ]; then
+    candidates+=("$MOSAIC_RUNTIME_BIN")
+  fi
+
+  if command -v npm >/dev/null 2>&1; then
+    local npm_prefix
+    npm_prefix=$(npm config get prefix 2>/dev/null) || true
+    if [ -n "$npm_prefix" ]; then
+      candidates+=("${npm_prefix}/bin")
+    fi
+  fi
+
+  candidates+=("$HOME/.npm-global/bin")
+  candidates+=("$HOME/.local/bin")
+
+  local prefix=""
+  for dir in "${candidates[@]}"; do
+    [ -d "$dir" ] || continue
+    case ":${PATH}:" in
+      *":${dir}:"*) continue ;;  # already present
+    esac
+    if [ -z "$prefix" ]; then
+      prefix="$dir"
+    else
+      case ":${prefix}:" in
+        *":${dir}:"*) ;;  # already in our prefix
+        *) prefix="${prefix}:${dir}" ;;
+      esac
+    fi
+  done
+
+  printf '%s' "$prefix"
+}
+
+MOSAIC_RUNTIME_BIN_PREFIX=$(_build_runtime_bin_prefix)
+
+# ── Build the pane command ────────────────────────────────────────────────────
+# The pane command must:
+#   - Export the augmented PATH so the runtime binary is found.
+#   - exec the agent command so the runtime is the pane's foreground process
+#     (makes `fleet ps` pane_current_command check reliable; no DRIFT false-positive).
+#
+# Quoting strategy: single-quote the inner shell snippet so that variable
+# references in MOSAIC_AGENT_COMMAND are NOT expanded here — they expand inside
+# the pane shell.  However, MOSAIC_RUNTIME_BIN_PREFIX and PATH must be expanded
+# NOW (in this script) because the pane shell inherits the tmux server
+# environment, not this script's env.
+#
+# We build the snippet as a double-quoted here-string embedded in a printf call
+# to avoid nested quoting problems.
+
+if [ -n "$MOSAIC_RUNTIME_BIN_PREFIX" ]; then
+  PANE_SHELL_SNIPPET="export PATH=\"${MOSAIC_RUNTIME_BIN_PREFIX}:\${PATH}\"; exec ${MOSAIC_AGENT_COMMAND}"
+else
+  PANE_SHELL_SNIPPET="exec ${MOSAIC_AGENT_COMMAND}"
+fi
+
 mkdir -p "$MOSAIC_AGENT_WORKDIR"
-exec tmux -L "$MOSAIC_TMUX_SOCKET" new-session -d -s "$AGENT_NAME" -c "$MOSAIC_AGENT_WORKDIR" "$MOSAIC_AGENT_COMMAND"
+exec tmux -L "$MOSAIC_TMUX_SOCKET" new-session -d -s "$AGENT_NAME" -c "$MOSAIC_AGENT_WORKDIR" \
+  bash -c "$PANE_SHELL_SNIPPET"

packages/mosaic/framework/tools/fleet/test-start-agent-session.sh

@@ -6,13 +6,26 @@ START="$SCRIPT_DIR/start-agent-session.sh"
 SOCKET="mosaic-agent-test-$RANDOM-$$"
 AGENT="agent-$RANDOM"
 WORKDIR=$(mktemp -d)
-trap 'tmux -L "$SOCKET" kill-server >/dev/null 2>&1 || true; rm -rf "$WORKDIR"' EXIT
+
+# Keep a single cleanup trap that accumulates resources.
+CLEANUP_DIRS=("$WORKDIR")
+CLEANUP_SOCKETS=("$SOCKET")
+trap '_cleanup' EXIT
+_cleanup() {
+  for s in "${CLEANUP_SOCKETS[@]:-}"; do
+    tmux -L "$s" kill-server >/dev/null 2>&1 || true
+  done
+  for d in "${CLEANUP_DIRS[@]:-}"; do
+    rm -rf "$d"
+  done
+}
 
 fail() {
   echo "FAIL: $*" >&2
   exit 1
 }
 
+# ── Test 1: basic session creation with workdir check ─────────────────────────
 MOSAIC_TMUX_SOCKET="$SOCKET" \
 MOSAIC_AGENT_WORKDIR="$WORKDIR" \
 MOSAIC_AGENT_COMMAND='bash --noprofile --norc -i' \
@@ -22,6 +35,7 @@ tmux -L "$SOCKET" has-session -t "=$AGENT:0.0" || fail "agent session was not cr
 actual_dir=$(tmux -L "$SOCKET" display-message -p -t "=$AGENT:0.0" '#{pane_current_path}')
 [ "$actual_dir" = "$WORKDIR" ] || fail "agent workdir mismatch: $actual_dir"
 
+# ── Test 2: idempotency (duplicate start prints 'already running') ─────────────
 MOSAIC_TMUX_SOCKET="$SOCKET" \
 MOSAIC_AGENT_WORKDIR="$WORKDIR" \
 MOSAIC_AGENT_COMMAND='bash --noprofile --norc -i' \
@@ -29,4 +43,109 @@ MOSAIC_AGENT_COMMAND='bash --noprofile --norc -i' \
 
 grep -qF 'already running' /tmp/mosaic-start-agent-idempotent.out || fail "duplicate start was not idempotent"
 
+# ── Test 3: runtime-bin PATH prefix is baked into the pane command ────────────
+#
+# We capture the command the script would hand to tmux by injecting a fake
+# 'tmux' shim into PATH.  The shim:
+#   - Intercepts 'new-session' calls and records its arguments to a file.
+#   - For 'has-session' calls, exits 1 (session does not exist) so the script
+#     proceeds to launch instead of printing "already running".
+#   - For all other subcommands, exits 0.
+#
+# Assertions:
+#   a) 'export PATH=' with the synthetic MOSAIC_RUNTIME_BIN prefix appears.
+#   b) 'exec' appears so the runtime replaces the wrapper shell.
+#   c) MOSAIC_AGENT_COMMAND with flags is forwarded intact.
+
+FAKE_BIN=$(mktemp -d)
+FAKE_RUNTIME_BIN=$(mktemp -d)
+TMUX_ARGS_FILE=$(mktemp)
+CLEANUP_DIRS+=("$FAKE_BIN" "$FAKE_RUNTIME_BIN")
+
+# Write the fake tmux shim (uses only positional args, no sourced vars).
+cat > "$FAKE_BIN/tmux" <<SHIM
+#!/usr/bin/env bash
+# Fake tmux: record new-session args; report has-session as missing.
+subcmd="\$3"  # argv: tmux -L <socket> <subcmd> ...
+if [ "\$subcmd" = "has-session" ]; then
+  exit 1   # session not found → script will attempt new-session
+fi
+if [ "\$subcmd" = "new-session" ]; then
+  printf '%s\n' "\$@" > "$TMUX_ARGS_FILE"
+  exit 0
+fi
+exit 0
+SHIM
+chmod +x "$FAKE_BIN/tmux"
+
+SOCKET3="mosaic-agent-test3-$RANDOM-$$"
+AGENT3="agent3-$RANDOM"
+WORKDIR3=$(mktemp -d)
+CLEANUP_DIRS+=("$WORKDIR3")
+
+PATH="$FAKE_BIN:$PATH" \
+MOSAIC_TMUX_SOCKET="$SOCKET3" \
+MOSAIC_AGENT_WORKDIR="$WORKDIR3" \
+MOSAIC_AGENT_RUNTIME="pi" \
+MOSAIC_RUNTIME_BIN="$FAKE_RUNTIME_BIN" \
+MOSAIC_AGENT_COMMAND="mosaic yolo pi --model openai-codex/gpt-5.5:high" \
+  "$START" "$AGENT3"
+
+all_args=$(cat "$TMUX_ARGS_FILE" 2>/dev/null || true)
+rm -f "$TMUX_ARGS_FILE"
+
+echo "--- captured tmux new-session args ---"
+echo "$all_args"
+echo "--- end args ---"
+
+# a) PATH prefix containing FAKE_RUNTIME_BIN must appear.
+echo "$all_args" | grep -qF "export PATH=" || fail "pane command does not export PATH"
+echo "$all_args" | grep -qF "$FAKE_RUNTIME_BIN" || fail "pane command does not include MOSAIC_RUNTIME_BIN in PATH prefix"
+
+# b) exec must appear so the runtime replaces the wrapper shell.
+echo "$all_args" | grep -qF "exec " || fail "pane command does not use exec"
+
+# c) Full MOSAIC_AGENT_COMMAND (with flags) must be forwarded.
+echo "$all_args" | grep -qF "mosaic yolo pi --model openai-codex/gpt-5.5:high" || \
+  fail "pane command does not forward MOSAIC_AGENT_COMMAND with flags intact"
+
+# ── Test 4: when no extra runtime-bin dirs exist, exec still appears ───────────
+TMUX_ARGS_FILE2=$(mktemp)
+FAKE_BIN2=$(mktemp -d)
+CLEANUP_DIRS+=("$FAKE_BIN2")
+
+cat > "$FAKE_BIN2/tmux" <<SHIM2
+#!/usr/bin/env bash
+subcmd="\$3"
+if [ "\$subcmd" = "has-session" ]; then exit 1; fi
+if [ "\$subcmd" = "new-session" ]; then
+  printf '%s\n' "\$@" > "$TMUX_ARGS_FILE2"
+  exit 0
+fi
+exit 0
+SHIM2
+chmod +x "$FAKE_BIN2/tmux"
+
+SOCKET4="mosaic-agent-test4-$RANDOM-$$"
+AGENT4="agent4-$RANDOM"
+WORKDIR4=$(mktemp -d)
+CLEANUP_DIRS+=("$WORKDIR4")
+
+# MOSAIC_RUNTIME_BIN points to a non-existent dir so prefix will be empty;
+# .npm-global/bin and .local/bin may or may not exist but we just want exec.
+PATH="$FAKE_BIN2:$PATH" \
+MOSAIC_TMUX_SOCKET="$SOCKET4" \
+MOSAIC_AGENT_WORKDIR="$WORKDIR4" \
+MOSAIC_AGENT_RUNTIME="pi" \
+MOSAIC_RUNTIME_BIN="/nonexistent-dir-$$" \
+MOSAIC_AGENT_COMMAND="mosaic yolo pi" \
+  "$START" "$AGENT4"
+
+all_args4=$(cat "$TMUX_ARGS_FILE2" 2>/dev/null || true)
+rm -f "$TMUX_ARGS_FILE2"
+rm -rf "$WORKDIR4"
+
+echo "$all_args4" | grep -qF "exec " || fail "pane command (no prefix dirs) does not use exec"
+echo "$all_args4" | grep -qF "mosaic yolo pi" || fail "pane command does not include agent command when no prefix"
+
 echo "ok - start-agent-session"