ops: keep tmux for agent sessions, remove bridge tmux guidance

Author: benvinegar

README.md

@@ -52,7 +52,7 @@ Baudbot is designed as shared engineering infrastructure, not a single-user desk
 | **CPU** | 2 vCPU | 4 vCPU |
 | **Disk** | 20 GB | 40 GB+ (repos, dependencies, Docker images) |
 
-System package dependencies (installed by `baudbot install`): `git`, `curl`, `iptables`, `docker`, `gh`, `jq`, `sudo`.
+System package dependencies (installed by `baudbot install`): `git`, `curl`, `tmux`, `iptables`, `docker`, `gh`, `jq`, `sudo`.
 
 ## Quick Start
 

bin/baudbot

@@ -131,8 +131,8 @@ usage() {
   echo "  restart        Restart the agent"
   echo "  status         Show agent status + deployed version + broker connection"
   echo "  logs           Tail agent logs"
-  echo "  attach         Attach to a running pi session (defaults to control-agent)"
-  echo "  sessions       List live pi sessions (name → id)"
+  echo "  attach         Attach to control-agent by default; supports --pi/--tmux"
+  echo "  sessions       List agent tmux and pi sessions (name → id)"
   echo ""
   echo -e "${BOLD}Setup:${RESET}"
   echo "  install        Bootstrap install from GitHub (download script, then escalate)"

bin/lib/baudbot-runtime.sh

@@ -305,9 +305,8 @@ cmd_logs() {
     exec journalctl -u baudbot -f "$@"
   fi
 
-  echo "No systemd unit. Check process + logs:"
-  echo "  pgrep -u baudbot_agent -af 'pi --session-control'"
-  echo "  tail -n 200 /home/baudbot_agent/.pi/agent/logs/runtime.log"
+  echo "No systemd unit. Check tmux sessions:"
+  echo "  sudo -u baudbot_agent tmux ls"
 }
 
 cmd_sessions() {
@@ -317,6 +316,14 @@ cmd_sessions() {
   local found alias alias_name alias_uuid sock sess_id name status
   declare -A ALIASES
 
+  echo -e "${BOLD}tmux sessions:${RESET}"
+  if sudo -u "$AGENT_USER" tmux ls 2>/dev/null; then
+    :
+  else
+    echo "  (none)"
+  fi
+
+  echo ""
   echo -e "${BOLD}pi sessions:${RESET}"
   PI_CONTROL_DIR="$(pi_control_dir "$AGENT_USER")"
   if [ ! -d "$PI_CONTROL_DIR" ]; then
@@ -370,26 +377,28 @@ cmd_attach() {
 
   local AGENT_USER="baudbot_agent"
   local AGENT_HOME="/home/$AGENT_USER"
+  local ATTACH_MODE="auto"
   local TARGET=""
-  local pi_target
+  local tmux_target pi_target
 
   while [ "$#" -gt 0 ]; do
     case "$1" in
       --pi)
-        # Backward-compatible no-op (pi is the only supported mode now)
+        ATTACH_MODE="pi"
         shift
         ;;
       --tmux)
-        echo "❌ --tmux is no longer supported. Use: sudo baudbot attach [session-name|session-id]"
-        exit 1
+        ATTACH_MODE="tmux"
+        shift
         ;;
       -h|--help)
-        echo "Usage: sudo baudbot attach [session-name|session-id]"
+        echo "Usage: sudo baudbot attach [--pi|--tmux] [session-name|session-id]"
         echo ""
         echo "Examples:"
         echo "  sudo baudbot attach                  # defaults to control-agent"
-        echo "  sudo baudbot attach control-agent"
-        echo "  sudo baudbot attach <uuid>"
+        echo "  sudo baudbot attach --pi control-agent"
+        echo "  sudo baudbot attach --pi <uuid>"
+        echo "  sudo baudbot attach --tmux sentry-agent"
         exit 0
         ;;
       *)
@@ -407,22 +416,82 @@ cmd_attach() {
     TARGET="control-agent"
   fi
 
+  attach_tmux_session() {
+    local tmux_target="$1"
+    echo -e "${BOLD}${CYAN}Attaching to tmux session:${RESET} $tmux_target"
+    echo -e "${GREEN}Safe detach:${RESET} Ctrl+b, d ${DIM}(keeps agent running)${RESET}"
+    echo ""
+    pause_before_attach
+    exec sudo -u "$AGENT_USER" tmux attach-session -t "$tmux_target"
+  }
+
   attach_pi_session() {
-    local target_session="$1"
-    echo -e "${BOLD}${CYAN}Attaching to pi session:${RESET} $target_session"
+    local pi_target="$1"
+    echo -e "${BOLD}${CYAN}Attaching to pi session:${RESET} $pi_target"
     echo -e "${BOLD}${YELLOW}Safe detach (does NOT stop the agent):${RESET}"
     echo -e "  ${YELLOW}1)${RESET} Press Ctrl+C once to clear input/cancel local prompt"
     echo -e "  ${YELLOW}2)${RESET} Press Ctrl+C again to exit this client"
     echo -e "  ${GREEN}Agent keeps running under systemd in the background.${RESET}"
     echo ""
     pause_before_attach
-    exec sudo -u "$AGENT_USER" bash -lc "export PATH='$AGENT_HOME/.varlock/bin:$AGENT_HOME/opt/node-v22.14.0-linux-x64/bin':\$PATH; cd ~; varlock run --path ~/.config/ -- pi --session '$target_session'"
+    exec sudo -u "$AGENT_USER" bash -lc "export PATH='$AGENT_HOME/.varlock/bin:$AGENT_HOME/opt/node-v22.14.0-linux-x64/bin':\$PATH; cd ~; varlock run --path ~/.config/ -- pi --session '$pi_target'"
+  }
+
+  choose_tmux_target() {
+    local requested="${1:-}"
+    local first
+
+    if [ -n "$requested" ]; then
+      if sudo -u "$AGENT_USER" tmux has-session -t "$requested" 2>/dev/null; then
+        echo "$requested"
+        return 0
+      fi
+      return 1
+    fi
+
+    first=$(sudo -u "$AGENT_USER" tmux ls -F '#{session_name}' 2>/dev/null | head -1)
+    [ -n "$first" ] || return 1
+    echo "$first"
+    return 0
+  }
+
+  choose_pi_target() {
+    local requested="${1:-}"
+    local resolved
+
+    if ! resolved=$(resolve_pi_session_id "$AGENT_USER" "$requested"); then
+      return 1
+    fi
+
+    [ -n "$resolved" ] || return 1
+    echo "$resolved"
+    return 0
   }
 
-  if pi_target=$(resolve_pi_session_id "$AGENT_USER" "$TARGET"); then
+  if [ "$ATTACH_MODE" = "tmux" ]; then
+    if tmux_target=$(choose_tmux_target "$TARGET"); then
+      attach_tmux_session "$tmux_target"
+    fi
+    echo "❌ tmux session not found. See: sudo baudbot sessions"
+    exit 1
+  fi
+
+  if [ "$ATTACH_MODE" = "pi" ]; then
+    if pi_target=$(choose_pi_target "$TARGET"); then
+      attach_pi_session "$pi_target"
+    fi
+    echo "❌ pi session not found. See: sudo baudbot sessions"
+    exit 1
+  fi
+
+  if pi_target=$(choose_pi_target "$TARGET"); then
     attach_pi_session "$pi_target"
   fi
 
-  echo "❌ pi session not found. See: sudo baudbot sessions"
+  if tmux_target=$(choose_tmux_target "$TARGET"); then
+    attach_tmux_session "$tmux_target"
+  fi
+
+  echo "❌ No matching tmux/pi session found. See: sudo baudbot sessions"
   exit 1
 }

install.sh

@@ -163,7 +163,7 @@ install_prereqs_ubuntu() {
 
   for attempt in $(seq 1 5); do
     if DEBIAN_FRONTEND=noninteractive apt-get -o DPkg::Lock::Timeout=120 update -qq \
-      && DEBIAN_FRONTEND=noninteractive apt-get -o DPkg::Lock::Timeout=120 install -y -qq git curl iptables docker.io gh jq sudo 2>&1 | tail -3; then
+      && DEBIAN_FRONTEND=noninteractive apt-get -o DPkg::Lock::Timeout=120 install -y -qq git curl tmux iptables docker.io gh jq sudo 2>&1 | tail -3; then
       return 0
     fi
 
@@ -179,10 +179,10 @@ install_prereqs_ubuntu() {
 }
 
 install_prereqs_arch() {
-  pacman -Syu --noconfirm --needed git curl iptables docker github-cli jq sudo 2>&1 | tail -5
+  pacman -Syu --noconfirm --needed git curl tmux iptables docker github-cli jq sudo 2>&1 | tail -5
 }
 
-info "Installing: git, curl, iptables, docker, gh, jq, sudo"
+info "Installing: git, curl, tmux, iptables, docker, gh, jq, sudo"
 "install_prereqs_$DISTRO"
 info "Prerequisites installed"
 
@@ -318,15 +318,12 @@ else
         warn "Agent didn't start — check: baudbot logs"
       fi
     else
-      RUNTIME_LOG_DIR="$BAUDBOT_HOME/.pi/agent/logs"
-      RUNTIME_LOG_FILE="$RUNTIME_LOG_DIR/runtime.log"
-      sudo -u baudbot_agent mkdir -p "$RUNTIME_LOG_DIR"
-      sudo -u baudbot_agent bash -lc "nohup '$BAUDBOT_HOME/runtime/start.sh' >> '$RUNTIME_LOG_FILE' 2>&1 &"
+      sudo -u baudbot_agent tmux new-session -d -s baudbot "$BAUDBOT_HOME/runtime/start.sh" 2>/dev/null || true
       sleep 2
-      if pgrep -u baudbot_agent -f "pi --session-control" >/dev/null 2>&1; then
+      if sudo -u baudbot_agent tmux has-session -t baudbot 2>/dev/null; then
         info "Agent is running ✓"
       else
-        warn "Agent didn't start — check: $RUNTIME_LOG_FILE"
+        warn "Agent didn't start — try: baudbot start --direct"
       fi
     fi
   else

pi/skills/control-agent/SKILL.md

@@ -198,22 +198,19 @@ git fetch origin
 git worktree add ~/workspace/worktrees/$BRANCH -b $BRANCH origin/main
 
 # 2. Launch the agent IN the worktree
-mkdir -p ~/.pi/agent/logs
-nohup bash -lc "cd ~/workspace/worktrees/$BRANCH && \
-  export PATH=\$HOME/.varlock/bin:\$HOME/opt/node-v22.14.0-linux-x64/bin:\$PATH && \
-  export PI_SESSION_NAME=$SESSION_NAME && \
-  exec varlock run --path ~/.config/ -- pi --session-control --skill ~/.pi/agent/skills/dev-agent --model <MODEL_FROM_TABLE_ABOVE>" \
-  > ~/.pi/agent/logs/$SESSION_NAME.log 2>&1 &
-DEV_PID=$!
-echo $DEV_PID > ~/.pi/agent/$SESSION_NAME.pid
+tmux new-session -d -s $SESSION_NAME \
+  "cd ~/workspace/worktrees/$BRANCH && \
+   export PATH=\$HOME/.varlock/bin:\$HOME/opt/node-v22.14.0-linux-x64/bin:\$PATH && \
+   export PI_SESSION_NAME=$SESSION_NAME && \
+   exec varlock run --path ~/.config/ -- pi --session-control --skill ~/.pi/agent/skills/dev-agent --model <MODEL_FROM_TABLE_ABOVE>"
 ```
 
 **Important notes:**
 - `cd` into the worktree BEFORE launching pi — this ensures pi discovers project context from the repo's CWD
+- Use `exec` so the tmux session exits when pi exits
 - Use `varlock run --path ~/.config/` to validate and inject env vars
 - Set `PI_SESSION_NAME` so the auto-name extension registers it
 - Include `--session-control` for `send_to_session` / `list_sessions`
-- Read logs with `tail -f ~/.pi/agent/logs/$SESSION_NAME.log`
 - Wait **~10 seconds** after spawning before sending messages (agent needs time to initialize)
 - Do NOT use `--name` (not a real pi CLI flag)
 
@@ -228,13 +225,8 @@ SESSION_NAME=dev-agent-myapp-a8b7b331
 REPO=myapp
 BRANCH=fix/some-descriptive-name
 
-# 1. Kill the process if still running
-PID_FILE=~/.pi/agent/$SESSION_NAME.pid
-if [ -f "$PID_FILE" ]; then
-  PID=$(cat "$PID_FILE" 2>/dev/null || true)
-  [ -n "$PID" ] && kill "$PID" 2>/dev/null || true
-  rm -f "$PID_FILE"
-fi
+# 1. Kill the tmux session (agent should have already exited, but ensure it)
+tmux kill-session -t $SESSION_NAME 2>/dev/null || true
 
 # 2. Remove the worktree
 cd ~/workspace/$REPO
@@ -317,10 +309,10 @@ This removes stale `.sock` files, cleans dead aliases, and restarts the Slack br
 - [ ] Find or create sentry-agent:
   1. Use `list_sessions` to look for a session named `sentry-agent`
   2. If found, use that session
-  3. If not found, launch as a normal background process (see Sentry Agent section)
+  3. If not found, launch with tmux (see Sentry Agent section)
   4. Wait ~8 seconds, then send role assignment
 - [ ] Send role assignment to the `sentry-agent` session
-- [ ] Clean up any stale dev-agent worktrees/background processes from previous runs
+- [ ] Clean up any stale dev-agent worktrees/tmux sessions from previous runs
 
 **Note**: Dev agents are NOT started at startup. They are spawned on-demand when tasks arrive.
 
@@ -338,9 +330,7 @@ The sentry-agent triages Sentry alerts and investigates critical issues via the
 | `OPENCODE_ZEN_API_KEY` | `opencode-zen/claude-haiku-4-5` |
 
 ```bash
-mkdir -p ~/.pi/agent/logs
-nohup bash -lc "export PATH=\$HOME/.varlock/bin:\$HOME/opt/node-v22.14.0-linux-x64/bin:\$PATH && export PI_SESSION_NAME=sentry-agent && exec varlock run --path ~/.config/ -- pi --session-control --skill ~/.pi/agent/skills/sentry-agent --model <MODEL_FROM_TABLE_ABOVE>" > ~/.pi/agent/logs/sentry-agent.log 2>&1 &
-echo $! > ~/.pi/agent/sentry-agent.pid
+tmux new-session -d -s sentry-agent "export PATH=\$HOME/.varlock/bin:\$HOME/opt/node-v22.14.0-linux-x64/bin:\$PATH && export PI_SESSION_NAME=sentry-agent && varlock run --path ~/.config/ -- pi --session-control --skill ~/.pi/agent/skills/sentry-agent --model <MODEL_FROM_TABLE_ABOVE>"
 ```
 
 **Model note**: `github-copilot/*` models reject Personal Access Tokens and will fail in non-interactive sessions.
@@ -351,12 +341,13 @@ The sentry-agent operates in **on-demand mode** — it does NOT poll. Sentry ale
 
 The `startup-cleanup.sh` script handles bridge (re)start automatically — it detects broker vs Socket Mode, reads the control-agent UUID, and starts the bridge as a normal background process.
 
-If you need to restart the bridge manually, run `startup-cleanup.sh` again and then inspect logs:
+If you need to restart the bridge manually, rerun startup cleanup and then inspect logs:
 ```bash
+bash ~/.pi/agent/skills/control-agent/startup-cleanup.sh UUID1 UUID2 UUID3
 tail -n 200 ~/.pi/agent/logs/slack-bridge.log
 ```
 
-Verify API readiness: `curl -s -o /dev/null -w '%{http_code}' -X POST http://127.0.0.1:7890/send -H 'Content-Type: application/json' -d '{}'` → should return `400`.
+Verify: `curl -s -o /dev/null -w '%{http_code}' -X POST http://127.0.0.1:7890/send -H 'Content-Type: application/json' -d '{}'` → should return `400`.
 
 The bridge forwards:
 - **Human @mentions and DMs** from allowed users → delivered to you with security boundaries for handling
@@ -369,9 +360,9 @@ Health checks run automatically every ~10 minutes via the `heartbeat.ts` extensi
 If you need to check manually, use `heartbeat trigger` to run all checks immediately.
 
 When the heartbeat reports a failure, take the appropriate action:
-1. **Missing sentry-agent**: Respawn as a background process and re-send role assignment.
-2. **Orphaned dev-agents**: Kill stale process + remove worktree.
-3. **Bridge down**: Restart via `startup-cleanup.sh` and read `~/.pi/agent/logs/slack-bridge.log`.
+1. **Missing sentry-agent**: Respawn with tmux and re-send role assignment.
+2. **Orphaned dev-agents**: Kill tmux session and remove worktree.
+3. **Bridge down**: Restart via `startup-cleanup.sh`, then check `~/.pi/agent/logs/slack-bridge.log`.
 4. **Stale worktrees**: `git worktree remove --force` + `rmdir` empty parents.
 5. **Stuck todos**: Escalate to user via Slack.
 

pi/skills/control-agent/memory/operational.md

@@ -8,5 +8,5 @@ Add entries under dated headings. Keep entries concise — one line per learning
 <!-- Example:
 ## 2026-02-17
 - Stale `.sock` files cause bridge "connect ENOENT" errors. Always run `startup-cleanup.sh` with live UUIDs on boot.
-- `varlock run` must be used (not `source .env`) when launching agents in background processes — ensures schema validation.
+- `varlock run` must be used (not `source .env`) when launching agents in tmux — ensures schema validation.
 -->