feat(tmux): deva-tmux — tmux as a built-in module, both transports

tmux interaction was four loose scripts with zero deva.sh integration;
the #406 draft built the right transport (ssh) but deleted the socat
fallback and stayed a loose script. This makes it a module:

- scripts/deva-tmux (baked into both images): ls/attach/tmux/bridge/
  setup/doctor over two transport backends. ssh default: authenticated,
  reboot-durable, runs the HOST's tmux client so there is no
  client/server protocol coupling. socat fallback: the old
  unauthenticated TCP daemon, kept for hosts without sshd, loud warning
  on every start. Both land on /tmp/host-tmux.sock — tmux-bridge
  (Layer 2) and htmux muscle memory work unchanged.
- Inert without provisioning: baked binary + no key + no daemon = no
  host reach. deva.sh --host-tmux is the opt-in — mounts ~/.ssh
  read-only (dedup-safe, user -v wins), passes DEVA_HOST_USER, and in
  repo mode mounts the launcher's deva-tmux over the image copy.
- deva.sh tmux command group (host side): setup writes your OWN
  authorized_keys — the #406 draft did that from inside the container
  via a docker host-mount, exactly the host-reach pattern this tool
  exists to gate; moving it host-side deletes the scariest code.
  host-daemon start|stop|status wraps the socat daemon (inline
  fallback for installed launchers). doctor for the host view.
- deva-bridge-tmux becomes a compat shim (old flags -> env ->
  deva-tmux bridge start --transport socat --foreground);
  deva-bridge-tmux-host unchanged; tmux-bridge stays vendored
  byte-for-byte.
- Fixed in live testing: a backgrounded ssh -N -L inherited the
  caller's stdout, so piping 'bridge start' hung forever waiting for
  EOF (the #406 draft shared this bug). Bridge children now detach
  stdio to a state-dir log.

Verified live against a real macOS host from inside a container: both
transports bridge the host server onto the socket, native tmux client
and tmux-bridge Layer 2 drive real panes through it, lifecycle
idempotent, socket cleaned on stop. Mount-shape suite asserts the
off/on/dedup provisioning shapes.

Close #412

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: lroolle

CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- `deva-tmux` (#412): tmux interaction is now a built-in module instead of
+  loose scripts. One in-container CLI, two transports — `ssh` (default:
+  authenticated, reboot-durable, runs the host's tmux client so there is
+  no client/server protocol coupling) and `socat` (fallback: the old
+  unauthenticated TCP daemon, kept for hosts without sshd, loud warning
+  every start). Both land the host server on `/tmp/host-tmux.sock`, so
+  `tmux-bridge` (Layer 2) and `htmux` muscle memory work unchanged.
+  Container->host stays opt-in: `deva.sh --host-tmux` mounts `~/.ssh`
+  read-only and passes `DEVA_HOST_USER`; without it the baked CLI is
+  inert. Host-side lifecycle moved where it belongs: `deva.sh tmux setup`
+  authorizes your key by writing your own `authorized_keys` (killing the
+  in-container docker-mount write from the #406 draft), `deva.sh tmux
+  host-daemon start|stop|status` manages the socat fallback, `deva.sh
+  tmux doctor` diagnoses the host side. `deva-bridge-tmux` is now a compat
+  shim. Verified live against a real host: both transports, bridge
+  lifecycle, native client + Layer 2 through the forwarded socket.
+
 ## [0.14.0] - 2026-07-10
 
 ### Added

DEV-LOGS.md

@@ -13,6 +13,16 @@
 - Minimal markdown markers, no unnecessary formatting, minimal emojis.
 - Reference issue numbers in the format `#<issue-number>` for easy linking.
 
+# [2026-07-10] Dev Log: deva-tmux — tmux as a built-in module, both transports #412
+- Why: tmux interaction was four loose scripts with zero deva.sh integration; #406 built the right transport (ssh) but deleted the socat fallback and stayed a loose script. Direction split matters: host->container (deva.sh shell) and agent<->agent (tmux-bridge) keep the sandbox; container->host breaks it and must be opt-in.
+- What:
+  - scripts/deva-tmux (new, baked into both images): ls/attach/tmux/bridge/setup/doctor with transport backends — ssh default (authenticated, launchd-durable, host-side tmux client so zero protocol coupling), socat fallback (unauthenticated TCP, warns loudly). DEVA_TMUX_TRANSPORT=auto|ssh|socat; auto probes ssh then socat. Both transports land on /tmp/host-tmux.sock -> tmux-bridge Layer 2 unchanged
+  - inert-without-provisioning is the security property: baked binary + no key + no daemon = no host reach. deva.sh --host-tmux is the opt-in: mounts ~/.ssh ro (dedup-safe, user -v wins), passes DEVA_HOST_USER, launcher's deva-tmux copy overrides the image copy in repo mode (skew insurance)
+  - deva.sh tmux command group (host side): setup writes your OWN authorized_keys — the #406 draft did this from inside the container via a docker host-mount, which is exactly the host-reach pattern the tool exists to gate; moving it host-side dissolved the scariest code. host-daemon start|stop|status wraps the socat daemon (inline fallback when scripts/ absent). doctor for the host view
+  - deva-bridge-tmux -> compat shim (old flags -> env -> deva-tmux bridge start --transport socat --foreground); deva-bridge-tmux-host unchanged; tmux-bridge stays vendored byte-for-byte (read-guard TTL idea goes upstream, not a fork)
+  - found+fixed in live test: backgrounded ssh -N -L inherited the caller's stdout, so `deva-tmux bridge start | tail` hung forever waiting for EOF — the #406 draft had the same latent bug. Bridge children now detach stdio to a state-dir log
+- Result: verified live against a real macOS host from inside the dev container — doctor sees both transports, ssh bridge + socat bridge both land the host server on the socket, native tmux client and tmux-bridge list work through it, lifecycle idempotent, socket cleaned on stop; mount-shape suite asserts off/on/dedup provisioning shapes; shellcheck severity=error clean
+
 # [2026-07-10] Dev Log: repo surface burnish #409
 - Why: product ships four agents but half the storefront said three; agents visiting the repo had no llms.txt; nightly 2026-07-09 failed on a transient ubuntu mirror sync and partially published (base pushed, rust did not — nightly/nightly-rust tags diverged a day)
 - What:

Dockerfile

@@ -234,12 +234,17 @@ RUN --mount=type=cache,target=/home/deva/.npm,uid=${DEVA_UID},gid=${DEVA_GID},sh
 USER root
 
 COPY docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
+# deva-tmux: container->host tmux CLI (ssh + socat transports). Baked but
+# inert without host-side provisioning (deva.sh --host-tmux / tmux setup).
+COPY scripts/deva-tmux /usr/local/bin/deva-tmux
+# deva-bridge-tmux: compat shim -> deva-tmux bridge --transport socat
 COPY scripts/deva-bridge-tmux /usr/local/bin/deva-bridge-tmux
 # tmux-bridge: vendored from smux (layer-2 agent comms CLI over tmux panes)
 # See scripts/tmux-bridge.VENDORED for upstream commit and SHA256 pin.
 COPY scripts/tmux-bridge /usr/local/bin/tmux-bridge
 
 RUN chmod 755 /usr/local/bin/docker-entrypoint.sh && \
+    chmod 755 /usr/local/bin/deva-tmux && \
     chmod 755 /usr/local/bin/deva-bridge-tmux && \
     chmod 755 /usr/local/bin/tmux-bridge && \
     chmod -R 755 /usr/local/bin/scripts || true

Dockerfile.rust

@@ -151,9 +151,14 @@ RUN --mount=type=cache,target=/home/deva/.npm,uid=${DEVA_UID},gid=${DEVA_GID},sh
 USER root
 
 COPY docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
+# deva-tmux: container->host tmux CLI (ssh + socat transports). Baked but
+# inert without host-side provisioning (deva.sh --host-tmux / tmux setup).
+COPY scripts/deva-tmux /usr/local/bin/deva-tmux
+# deva-bridge-tmux: compat shim -> deva-tmux bridge --transport socat
 COPY scripts/deva-bridge-tmux /usr/local/bin/deva-bridge-tmux
 
 RUN chmod 755 /usr/local/bin/docker-entrypoint.sh && \
+    chmod 755 /usr/local/bin/deva-tmux && \
     chmod 755 /usr/local/bin/deva-bridge-tmux && \
     chmod -R 755 /usr/local/bin/scripts || true
 

deva.sh

@@ -79,6 +79,7 @@ GLOBAL_MODE=false
 DEBUG_MODE=false
 DRY_RUN=false
 CODEX_BROWSER_MCP=false
+HOST_TMUX=false
 
 if [ -t 0 ] && [ -t 1 ]; then
     DOCKER_TERMINAL_ARGS=(-it)
@@ -120,6 +121,8 @@ Container management commands (docker/tmux-style):
   deva.sh insight [args]      Generate data report (ccx insight pass-through)
   deva.sh ccx [-g] [cmd] [args]
                               Run any ccx command inside a container
+  deva.sh tmux <cmd>         Host-side tmux lifecycle: setup (ssh key),
+                              host-daemon start|stop|status (socat fallback), doctor
 
 Advanced:
   deva.sh --show-config      Show resolved configuration (debug)
@@ -136,6 +139,12 @@ Deva flags:
   -Q, --quick             Bare mode: no host config mounts, no .deva loading, no autolink,
                           implies --rm. Like emacs -Q. Mutually exclusive with -c.
   --host-net              Use host networking for the agent container
+  --host-tmux             Opt in to container->host tmux: mounts ~/.ssh (ro)
+                          and passes DEVA_HOST_USER so the in-container
+                          deva-tmux CLI can reach the host tmux server.
+                          Off by default - it lets the container run
+                          commands on the host. Inside: deva-tmux doctor.
+                          Docs: docs/tmux-bridge-agent-comms.md
   --browser-mcp           Codex only: wire Playwright MCP through Codex config overrides.
                           Uses the rust profile because browser runtime deps live there.
                           Alias: --with-browser
@@ -749,6 +758,30 @@ prepare_claude_chrome_bridge() {
     USER_ENVS+=("DEVA_CHROME_HOST_BRIDGE_DIR=$bridge_mount")
 }
 
+# Container->host tmux is opt-in (--host-tmux). The in-container CLI
+# (deva-tmux) is baked into the image but inert without this provisioning:
+# the ssh transport becomes usable only when the user's ~/.ssh (read-only)
+# and host username ride in. In a repo checkout the launcher's copy of
+# deva-tmux is mounted over the image copy so flag semantics never skew
+# against an older image; installed launchers rely on the image copy.
+prepare_host_tmux() {
+    [ "$HOST_TMUX" = true ] || return 0
+
+    local host_user
+    host_user="$(configured_env_value DEVA_HOST_USER || true)"
+    if [ -z "$host_user" ]; then
+        host_user="$(id -un)"
+    fi
+
+    if [ -d "$HOME/.ssh" ] && ! user_volume_mounts_target "/home/deva/.ssh"; then
+        USER_VOLUMES+=("$HOME/.ssh:/home/deva/.ssh:ro")
+    fi
+    if [ -f "$SCRIPT_DIR/scripts/deva-tmux" ] && ! user_volume_mounts_target "/usr/local/bin/deva-tmux"; then
+        USER_VOLUMES+=("$SCRIPT_DIR/scripts/deva-tmux:/usr/local/bin/deva-tmux:ro")
+    fi
+    USER_ENVS+=("DEVA_HOST_USER=$host_user")
+}
+
 prepare_browser_integration() {
     [ "$CODEX_BROWSER_MCP" = true ] || return 0
 
@@ -1271,6 +1304,181 @@ shorten_path() {
     fi
 }
 
+# --- deva.sh tmux: host-side lifecycle for container->host tmux ------------
+# The container side is deva-tmux (baked into the image, inert without
+# provisioning). The host side owns exactly what must not be done from
+# inside the sandbox: authorizing the ssh key and running the socat daemon.
+
+tmux_host_setup() {
+    local marker="deva-host-tmux"
+    local pub=""
+    for k in "$HOME/.ssh/id_ed25519.pub" "$HOME/.ssh/id_rsa.pub"; do
+        [ -f "$k" ] && { pub="$k"; break; }
+    done
+    if [ -z "$pub" ]; then
+        echo "error: no ssh keypair found in ~/.ssh" >&2
+        echo "generate one first:  ssh-keygen -t ed25519" >&2
+        echo "then re-run:         deva.sh tmux setup" >&2
+        return 1
+    fi
+
+    mkdir -p "$HOME/.ssh"
+    touch "$HOME/.ssh/authorized_keys"
+    chmod 600 "$HOME/.ssh/authorized_keys"
+    local pubkey
+    pubkey="$(cat "$pub")"
+    if grep -qF "$pubkey" "$HOME/.ssh/authorized_keys"; then
+        echo "ok: key already authorized ($pub)"
+    else
+        printf '%s %s\n' "$pubkey" "$marker" >>"$HOME/.ssh/authorized_keys"
+        echo "ok: key authorized ($pub)"
+        echo "undo: remove the '$marker' line from ~/.ssh/authorized_keys"
+    fi
+
+    if timeout 3 bash -c 'exec 3<>/dev/tcp/127.0.0.1/22' 2>/dev/null; then
+        echo "ok: sshd is listening on port 22"
+    else
+        echo "warning: sshd is not reachable on 127.0.0.1:22" >&2
+        echo "macOS: System Settings > General > Sharing > Remote Login" >&2
+        echo "       or: sudo systemsetup -setremotelogin on" >&2
+        return 1
+    fi
+    echo "container side: deva.sh --host-tmux <agent>, then: deva-tmux doctor"
+}
+
+# The socat fallback daemon exposes the host tmux socket over TCP with NO
+# authentication — any process that can reach the port drives your tmux.
+# Prefer the ssh transport; this exists for hosts without Remote Login.
+tmux_host_daemon() {
+    local action="${1:-status}"
+    local state_dir="${XDG_STATE_HOME:-$HOME/.local/state}/deva/tmux"
+    local pid_file="$state_dir/host-daemon.pid"
+    local daemon="$SCRIPT_DIR/scripts/deva-bridge-tmux-host"
+    local bind="${DEVA_BRIDGE_BIND:-127.0.0.1}"
+    local port="${DEVA_BRIDGE_PORT:-41555}"
+
+    case "$action" in
+    status)
+        if [ -f "$pid_file" ] && kill -0 "$(cat "$pid_file")" 2>/dev/null; then
+            echo "host-daemon up (pid $(cat "$pid_file"), ${bind}:${port}) — UNAUTHENTICATED, prefer ssh"
+        else
+            echo "host-daemon down"
+            return 1
+        fi
+        ;;
+    stop)
+        if [ -f "$pid_file" ]; then
+            kill "$(cat "$pid_file")" 2>/dev/null || true
+            rm -f "$pid_file"
+            echo "host-daemon stopped"
+        else
+            echo "host-daemon not running"
+        fi
+        ;;
+    start)
+        if [ -f "$pid_file" ] && kill -0 "$(cat "$pid_file")" 2>/dev/null; then
+            echo "host-daemon already up (pid $(cat "$pid_file"))"
+            return 0
+        fi
+        command -v socat >/dev/null 2>&1 || {
+            echo "error: socat not installed on host" >&2
+            return 1
+        }
+        local socket
+        socket="$(tmux display-message -p '#{socket_path}' 2>/dev/null || true)"
+        [ -n "$socket" ] || socket="/private/tmp/tmux-$(id -u)/default"
+        if [ ! -S "$socket" ]; then
+            echo "error: no host tmux server socket at $socket (start tmux first)" >&2
+            return 1
+        fi
+        echo "WARNING: exposing host tmux over UNAUTHENTICATED ${bind}:${port}" >&2
+        echo "         any local process gains tmux control; prefer: deva.sh tmux setup" >&2
+        mkdir -p "$state_dir"
+        if [ -x "$daemon" ]; then
+            nohup "$daemon" -q -b "$bind" -p "$port" -s "$socket" >>"$state_dir/host-daemon.log" 2>&1 &
+        else
+            # Installed launcher without the repo's scripts/: same mechanics inline.
+            nohup socat "TCP-LISTEN:${port},bind=${bind},reuseaddr,fork" "UNIX-CONNECT:${socket}" >>"$state_dir/host-daemon.log" 2>&1 &
+        fi
+        echo $! >"$pid_file"
+        sleep 0.3
+        if kill -0 "$(cat "$pid_file")" 2>/dev/null; then
+            echo "host-daemon up (pid $(cat "$pid_file"), ${bind}:${port} -> ${socket})"
+            echo "container side: deva-tmux bridge start --transport socat"
+        else
+            rm -f "$pid_file"
+            echo "error: host-daemon failed to start (see $state_dir/host-daemon.log)" >&2
+            return 1
+        fi
+        ;;
+    *)
+        echo "error: unknown host-daemon action: $action (start|stop|status)" >&2
+        return 1
+        ;;
+    esac
+}
+
+tmux_host_doctor() {
+    echo "deva tmux doctor (host side)"
+    echo "---"
+    local pub=""
+    for k in "$HOME/.ssh/id_ed25519.pub" "$HOME/.ssh/id_rsa.pub"; do
+        [ -f "$k" ] && { pub="$k"; break; }
+    done
+    if [ -n "$pub" ]; then
+        echo "ssh keypair:     $pub"
+        if [ -f "$HOME/.ssh/authorized_keys" ] && grep -qF "$(cat "$pub")" "$HOME/.ssh/authorized_keys"; then
+            echo "authorized:      yes"
+        else
+            echo "authorized:      NO (run: deva.sh tmux setup)"
+        fi
+    else
+        echo "ssh keypair:     NONE (ssh-keygen -t ed25519)"
+    fi
+    if timeout 3 bash -c 'exec 3<>/dev/tcp/127.0.0.1/22' 2>/dev/null; then
+        echo "sshd port 22:    open"
+    else
+        echo "sshd port 22:    CLOSED (macOS: Sharing > Remote Login)"
+    fi
+    local sessions
+    sessions="$(tmux ls 2>/dev/null | wc -l | tr -d ' ')"
+    echo "tmux sessions:   $sessions"
+    tmux_host_daemon status || true
+    echo "---"
+    echo "container side:  deva.sh --host-tmux <agent>, then deva-tmux doctor"
+}
+
+cmd_tmux() {
+    local sub="${1:-help}"
+    [ $# -gt 0 ] && shift
+    case "$sub" in
+    setup) tmux_host_setup "$@" ;;
+    host-daemon) tmux_host_daemon "${1:-status}" ;;
+    doctor) tmux_host_doctor ;;
+    help | -h | --help)
+        cat <<'EOF'
+deva.sh tmux - host-side lifecycle for container->host tmux
+
+Usage:
+  deva.sh tmux setup                          Authorize your ssh key (ssh transport, default)
+  deva.sh tmux host-daemon start|stop|status  socat fallback daemon (UNAUTHENTICATED)
+  deva.sh tmux doctor                         Host-side diagnosis
+
+Container side:
+  deva.sh --host-tmux <agent>                 Opt-in provisioning at launch
+  deva-tmux ls|attach|bridge|doctor           In-container CLI (both transports)
+  tmux-bridge list|read|type|...              Agent<->agent pane comms (Layer 2)
+
+Docs: docs/tmux-bridge-agent-comms.md
+EOF
+        ;;
+    *)
+        echo "error: unknown tmux subcommand: $sub (setup|host-daemon|doctor|help)" >&2
+        exit 1
+        ;;
+    esac
+}
+
 cmd_status() {
     local show_all=false verbose=false
 
@@ -2856,6 +3064,11 @@ parse_wrapper_args() {
             i=$((i + 1))
             continue
             ;;
+        --host-tmux)
+            HOST_TMUX=true
+            i=$((i + 1))
+            continue
+            ;;
         --rm)
             EPHEMERAL_MODE=true
             i=$((i + 1))
@@ -2976,7 +3189,14 @@ if [ ${#PRE_ARGS[@]} -gt 0 ]; then
     done
 fi
 
-if [ ${#PRE_ARGS[@]} -gt 0 ]; then
+# `deva.sh tmux <sub> [args]` is a command group: only the FIRST token
+# selects it, so subcommand args (status, stop, ...) can't collide with the
+# management-mode tokens scanned below.
+if [ "${PRE_ARGS[0]:-}" = "tmux" ]; then
+    MANAGEMENT_MODE="tmux"
+fi
+
+if [ ${#PRE_ARGS[@]} -gt 0 ] && [ "$MANAGEMENT_MODE" != "tmux" ]; then
     for tok in "${PRE_ARGS[@]}"; do
         case "$tok" in
         help | --help | -h)
@@ -3023,6 +3243,11 @@ if [ ${#PRE_ARGS[@]} -gt 0 ]; then
 fi
 
 if [ "$MANAGEMENT_MODE" != "launch" ]; then
+    if [ "$MANAGEMENT_MODE" = "tmux" ]; then
+        cmd_tmux "${PRE_ARGS[@]:1}"
+        exit $?
+    fi
+
     if [ "$MANAGEMENT_MODE" = "ps" ]; then
         list_containers_pretty
         exit 0
@@ -3340,6 +3565,7 @@ autolink_legacy_into_deva_root() {
 check_agent "$ACTIVE_AGENT"
 prepare_browser_integration
 prepare_claude_chrome_bridge
+prepare_host_tmux
 append_shared_agents_mount
 
 if [ -n "$CONFIG_HOME" ] && [ "$DRY_RUN" != true ]; then