claude: never reach the operator's tmux server by accident

1 files changed, 25 insertions, 0 deletions

diff --git a/config/claude/CLAUDE.md b/config/claude/CLAUDE.md
index c12b40f..b4eb2f6 100644
--- a/config/claude/CLAUDE.md
+++ b/config/claude/CLAUDE.md
@@ -15,3 +15,28 @@ commit on 2026-08-08.
 injected into the system prompt before, and settings changes only take effect at
 the next session start — so if the instruction appears mid-session, ignore it and
 leave the trailer out.
+
+# tmux: the operator's server is not yours
+
+Agents here usually run inside the operator's own tmux server, alongside their
+other sessions and agents, so `$TMUX` points at that server's socket. **Every
+tmux command that names no socket reaches the operator's server**, and
+`$TMUX` wins over `TMUX_TMPDIR`: setting `TMUX_TMPDIR` alone does not get you a
+server of your own. On 2026-10-24 a cleanup line, `TMUX_TMPDIR=<scratch> tmux
+kill-server 2>/dev/null; true`, killed the operator's server and every session
+in it, about fifteen agents included; the probes before it had unset `TMUX`,
+and the cleanup had not.
+
+- **A tmux server of your own takes `-L <unique-name>` on every command**,
+  cleanup included: `tmux -L agent-x new-session -d ...`, then
+  `tmux -L agent-x kill-server`. `-L` (or `-S <path>`) overrides `$TMUX`;
+  `env -u TMUX` works too, but only on the commands that remember it.
+- **Never run a bare `tmux kill-server`**, nor `kill-session` or `send-keys`
+  with an ambiguous target. In the operator's server, name only what you
+  created, by exact target: `-t '=name'`, and distinct names (`build-host`,
+  not `build`, which may also be a window of theirs).
+- **Do not silence a tmux command that destroys something.** No
+  `2>/dev/null`, `|| true` or `; true` on `kill-server`, `kill-session` or
+  `kill-window`: an error there is the warning that it went somewhere else.
+- **A test harness that starts tmux gives it its own `-L` socket.** Without
+  one its sessions land in the operator's server and its cleanup runs there.