fix(tmux): unbind destructive key bindings and disable automatic-rename - #664
Conversation
Research and specification for preventing accidental tmux session destruction during agent workflows. Assistant-model: Claude Code
Unbind tmux keybindings that could destroy windows, panes, or sessions during agent workflows. Enable remain-on-exit to keep panes alive after process exits and add a pane-died hook to auto-respawn crashed processes. - Remove pane-splitting bindings (managed programmatically) - Unbind kill, rename, detach, create, and navigation keys - Set remain-on-exit on and automatic-rename off - Add pane-died hook for non-zero exit respawn - Add integration tests for remain-on-exit, killWindow compat, automatic-rename off, and crash respawn Assistant-model: Claude Code
Global workflow templates at ~/.atomic/workflows/ were being included in coverage and dragging the total below the 85% threshold. The existing .atomic/** pattern only matched the local project directory, not the parent path (../.atomic/**). Assistant-model: Claude Code
The previous unbind rules blocked legitimate tmux interactions (command prompt, detach, window navigation, splits) making the session difficult to use. Keep only the essential protections (kill-server, kill-session, kill-pane, rename) while restoring normal tmux usability. Assistant-model: Claude Code
claude
Bot
changed the title
PR Review — tmux destructive actions preventionThanks for the thorough research and spec docs. The intent is clear and the direction is right. However, there is a meaningful gap between the spec and the implementation, plus a few correctness/testing concerns worth addressing before merge. 🚨 Blocking: implementation does not match specThe spec (section 5.1.1) lists ~18 unbinds and its functional goals (3.1) explicitly include users CANNOT access the tmux command prompt, CANNOT detach, CANNOT create new windows or split panes. The actual Still reachable from
Either (a) bring the config in line with §5.1.1 of the spec, or (b) update the spec/PR description to reflect the narrower scope that was actually shipped. As-is, merging this gives users a false sense of lockdown — the most dangerous escape (
|
There was a problem hiding this comment.
Pull request overview
This PR strengthens Atomic’s tmux-managed workflow sessions by hardening the bundled tmux.conf and adding integration tests/docs to prevent user actions (and process exits) from breaking the workflow orchestrator’s expected tmux session/window structure.
Changes:
- Updates
src/sdk/runtime/tmux.confto add protection behaviors (unbind some destructive keys, keep panes viaremain-on-exit, disableautomatic-rename, and respawn onpane-diedfor non-zero exits). - Adds tmux integration tests covering
remain-on-exit, programmatickillWindow, window naming stability, and thepane-diedhook behavior. - Adds a detailed design spec + supporting research docs, and tweaks Bun coverage ignore patterns.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/sdk/runtime/tmux.test.ts | Adds integration tests for new tmux.conf behaviors (remain-on-exit, killWindow, rename stability, pane-died). |
| src/sdk/runtime/tmux.conf | Introduces workflow-protection directives and crash/exit handling via tmux options/hooks; removes custom split bindings. |
| specs/2026-04-16-tmux-destructive-actions-prevention.md | New technical design doc describing the intended destructive-action prevention approach. |
| research/web/2026-04-16-tmux-preventing-destructive-actions.md | New comprehensive reference material on tmux options/hooks/keybinding lockdown. |
| research/docs/2026-04-16-tmux-destructive-actions-prevention.md | New repo-specific research writeup tying tmux risks to Atomic’s workflow runtime. |
| bunfig.toml | Extends coverage ignore patterns to include global workflow templates outside repo root. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| # Auto-respawn panes that die with a non-zero exit code (crash). | ||
| # Clean exits (code 0) keep the dead pane visible for inspection. | ||
| set-hook -g pane-died "if -F '#{!=:#{pane_dead_status},0}' 'respawn-pane'" |
There was a problem hiding this comment.
The global pane-died → respawn-pane hook can create a tight respawn loop if a command repeatedly exits non-zero (e.g., misconfiguration or a persistent crash), which can spike CPU and make sessions hard to shut down cleanly. Consider adding a small delay/backoff (e.g., via run-shell) and/or a guard/limit (per-pane counter/user option) so repeated failures don’t cause an unbounded respawn cycle.
| # Auto-respawn panes that die with a non-zero exit code (crash). | |
| # Clean exits (code 0) keep the dead pane visible for inspection. | |
| set-hook -g pane-died "if -F '#{!=:#{pane_dead_status},0}' 'respawn-pane'" | |
| # Auto-respawn panes that die with a non-zero exit code (crash), | |
| # but add a short delay and a per-pane retry cap to avoid tight | |
| # respawn loops when a command is persistently misconfigured or crashing. | |
| # Clean exits (code 0) keep the dead pane visible for inspection. | |
| set-hook -g pane-died "if -F '#{!=:#{pane_dead_status},0}' 'run-shell -b \"count=\\$(tmux display-message -p -t #{pane_id} \\\"#{@atomic_respawn_count}\\\"); case \\$count in \\\"\\\" ) count=0 ;; esac; if [ \\$count -lt 5 ]; then next=\\$((count + 1)); tmux set-option -pt #{pane_id} @atomic_respawn_count \\$next; sleep 1; tmux respawn-pane -k -t #{pane_id}; else tmux display-message -t #{pane_id} \\\"Pane #{pane_id} reached respawn limit (5); not restarting automatically.\\\"; fi\"'" |
|
|
||
| describe.if(tmuxAvailable)("tmux.conf: pane-died hook respawns crashed processes (non-zero exit)", () => { | ||
| afterAll(() => { | ||
| killSession(CRASH_SESSION); | ||
| }); | ||
|
|
||
| test("pane is alive after crashing with a non-zero exit code", async () => { | ||
| // Start with a command that exits with non-zero — the pane-died hook should respawn it | ||
| createSession(CRASH_SESSION, "exit 1", "crash-test"); | ||
| // Wait for initial crash and respawn cycle | ||
| await Bun.sleep(1000); | ||
|
|
||
| // The session should still exist and list-panes should return ok (pane alive) | ||
| const result = tmuxRun(["list-panes", "-t", CRASH_SESSION]); | ||
| expect(result.ok).toBe(true); |
There was a problem hiding this comment.
This test doesn’t currently validate that the pane was actually respawned: tmux list-panes will succeed even if the pane is still in a dead state under remain-on-exit. Also, using an always-failing command (exit 1) risks triggering repeated respawns. Consider asserting on a pane liveness flag (e.g., #{pane_dead} / #{pane_dead_status}) and using a command that fails once then stays running so the test can prove the hook recovered successfully.
| describe.if(tmuxAvailable)("tmux.conf: pane-died hook respawns crashed processes (non-zero exit)", () => { | |
| afterAll(() => { | |
| killSession(CRASH_SESSION); | |
| }); | |
| test("pane is alive after crashing with a non-zero exit code", async () => { | |
| // Start with a command that exits with non-zero — the pane-died hook should respawn it | |
| createSession(CRASH_SESSION, "exit 1", "crash-test"); | |
| // Wait for initial crash and respawn cycle | |
| await Bun.sleep(1000); | |
| // The session should still exist and list-panes should return ok (pane alive) | |
| const result = tmuxRun(["list-panes", "-t", CRASH_SESSION]); | |
| expect(result.ok).toBe(true); | |
| const CRASH_MARKER = `/tmp/${CRASH_SESSION}.respawned`; | |
| describe.if(tmuxAvailable)("tmux.conf: pane-died hook respawns crashed processes (non-zero exit)", () => { | |
| afterAll(() => { | |
| killSession(CRASH_SESSION); | |
| Bun.spawnSync(["rm", "-f", CRASH_MARKER]); | |
| }); | |
| test("pane is alive after crashing with a non-zero exit code", async () => { | |
| Bun.spawnSync(["rm", "-f", CRASH_MARKER]); | |
| // Fail once, then stay running after the pane-died hook respawns the pane. | |
| const paneId = createSession( | |
| CRASH_SESSION, | |
| `sh -lc 'if [ ! -f "${CRASH_MARKER}" ]; then : > "${CRASH_MARKER}"; exit 1; fi; exec tail -f /dev/null'`, | |
| "crash-test", | |
| ); | |
| const deadline = Date.now() + 5000; | |
| let paneDead: string | undefined; | |
| let paneCommand: string | undefined; | |
| while (Date.now() < deadline) { | |
| const result = tmuxRun([ | |
| "list-panes", | |
| "-t", | |
| paneId, | |
| "-F", | |
| "#{pane_dead} #{pane_current_command}", | |
| ]); | |
| expect(result.ok).toBe(true); | |
| if (result.ok) { | |
| const [dead, command] = result.stdout.trim().split(/\s+/, 2); | |
| paneDead = dead; | |
| paneCommand = command; | |
| if (paneDead === "0" && paneCommand === "tail") { | |
| break; | |
| } | |
| } | |
| await Bun.sleep(200); | |
| } | |
| expect(paneDead).toBe("0"); | |
| expect(paneCommand).toBe("tail"); |
| test("window name does not change after running a command in the pane", async () => { | ||
| const originalName = "my-named-window"; | ||
| const paneId = createSession(AUTONAME_SESSION, "bash", originalName); | ||
| await Bun.sleep(300); | ||
|
|
||
| // Run a command in the pane — with automatic-rename on, this would change the window name | ||
| const result = tmuxRun(["send-keys", "-t", paneId, "echo test", "Enter"]); | ||
| expect(result.ok).toBe(true); | ||
| await Bun.sleep(300); | ||
|
|
||
| const nameResult = tmuxRun(["list-windows", "-t", AUTONAME_SESSION, "-F", "#{window_name}"]); | ||
| expect(nameResult.ok).toBe(true); | ||
| if (nameResult.ok) { | ||
| const windowNames = nameResult.stdout.split("\n").map((n) => n.trim()).filter(Boolean); | ||
| expect(windowNames).toContain(originalName); |
There was a problem hiding this comment.
This automatic-rename test likely passes even without automatic-rename off because tmux typically disables automatic renaming for a window once it has an explicit name set at creation. To actually test the config, consider asserting the option value directly (show-window-options -g automatic-rename) or constructing a scenario where automatic renaming would occur (unnamed window) and verifying it does not.
| test("window name does not change after running a command in the pane", async () => { | |
| const originalName = "my-named-window"; | |
| const paneId = createSession(AUTONAME_SESSION, "bash", originalName); | |
| await Bun.sleep(300); | |
| // Run a command in the pane — with automatic-rename on, this would change the window name | |
| const result = tmuxRun(["send-keys", "-t", paneId, "echo test", "Enter"]); | |
| expect(result.ok).toBe(true); | |
| await Bun.sleep(300); | |
| const nameResult = tmuxRun(["list-windows", "-t", AUTONAME_SESSION, "-F", "#{window_name}"]); | |
| expect(nameResult.ok).toBe(true); | |
| if (nameResult.ok) { | |
| const windowNames = nameResult.stdout.split("\n").map((n) => n.trim()).filter(Boolean); | |
| expect(windowNames).toContain(originalName); | |
| test("global automatic-rename option is disabled", () => { | |
| const optionResult = tmuxRun(["show-window-options", "-gv", "automatic-rename"]); | |
| expect(optionResult.ok).toBe(true); | |
| if (optionResult.ok) { | |
| expect(optionResult.stdout.trim()).toBe("off"); |
| # ── Workflow protection: unbind destructive defaults ────────────── | ||
| # Atomic manages the tmux session lifecycle programmatically. Users should | ||
| # interact with agents and navigate via Ctrl+G / Ctrl+\ / the graph panel. | ||
| # The prefix key (C-b) is kept only for copy-mode entry (C-b [). | ||
|
|
||
| # Prevent window/pane destruction | ||
| unbind & # kill-window | ||
| unbind x # kill-pane | ||
|
|
||
| # Prevent renaming | ||
| unbind , # rename-window | ||
| unbind '$' # rename-session | ||
|
|
There was a problem hiding this comment.
The “workflow protection” unbind list is incomplete: tmux command prompt (prefix + :), detach (prefix + d/D), and uncontrolled window/pane creation (prefix + c / " / %) are still enabled, so users can still run destructive actions that break Atomic’s managed session/window invariants. Consider unbinding those defaults here (and any other destructive prefix bindings you intend to block) so the config matches the intended protection level described in the accompanying spec/research.
Remove remain-on-exit and pane-died respawn hook that interfered with normal tmux operation. Add standard pane splitting keybindings (- and |) with current path inheritance. Assistant-model: Claude Code
claude
Bot
changed the title
Review: PR #664 —
|
| Claimed in PR/spec | Present in src/sdk/runtime/tmux.conf? |
|---|---|
remain-on-exit on (panes stay visible after exit) |
No |
set-hook -g pane-died "if -F '#{!=:#{pane_dead_status},0}' 'respawn-pane'" |
No |
unbind : (command-prompt — highest-risk binding, lets user run arbitrary kill-session/kill-server) |
No |
unbind d / unbind D (detach) |
No |
unbind c (new-window) |
No |
unbind '"' / unbind % / unbind ! (splits, break-pane) |
No |
unbind n / unbind p / unbind w / unbind L |
No |
unbind '(' / unbind ')' / unbind s |
No |
unbind . / unbind C-z |
No |
The line 74 comment — "The prefix key (C-b) is kept only for copy-mode entry (C-b [)" — is therefore misleading: C-b :, C-b d, C-b c, C-b ", C-b %, C-b w, etc. are all still active. Since C-b : → command-prompt was explicitly called out in the research as the most dangerous binding (user can type kill-session etc.), omitting it defeats a primary goal of this PR.
2. Two of the four new tests will fail against the shipped config.
In tests/sdk/runtime/tmux.test.ts:
"tmux.conf: remain-on-exit keeps pane alive after process exits"(~lines 1310–1323): creates a session with"echo done && exit 0"and after 800 ms assertssessionExists(...)istrue. Withoutremain-on-exit on, the shell's exit destroys the only pane → window → session, sosessionExistsreturnsfalse. This test only passes if the missing directive is added."tmux.conf: pane-died hook respawns crashed processes (non-zero exit)"(~lines 1395–1401): creates a session with"exit 1"and expectslist-panesto still succeed after 1 s. This requires bothremain-on-exit(to keep the pane dead-but-alive) and thepane-diedrespawn hook. Neither is in the config →list-panes -t <session>will return non-ok because the session is already destroyed.
Please either (a) add the missing directives so the tests pass, or (b) if the scope has intentionally narrowed, delete those two tests and update the PR description/spec to match. Right now they are effectively specifying behavior that doesn't exist.
3. PR description claim about pane splitting is inaccurate.
The summary says: "Pane splitting removed: Removed | / - split-window bindings — session layout is managed programmatically by Atomic." The diff shows them deleted from lines 29–32 and re-added at the bottom of the file (lines 88–89). Net effect: bind - and bind | split bindings are still active. Either remove them for real, or drop that bullet from the description.
Other feedback
4. Test assertions are weaker than they could be. The pane-died test only checks that list-panes returns ok — it doesn't verify the pane was actually respawned with the original command. A stronger assertion would check that after respawn the pane's process is running, e.g. via pane_dead being 0 or by sending a command and observing it executes. As written, even a sleeping zombie pane could pass.
5. Timing-based waits (Bun.sleep(800) / Bun.sleep(1000)) are flaky in CI. These suites are guarded by describe.if(tmuxAvailable) so they'll only run where tmux exists, but consider polling (waitFor-style) on the observable condition rather than fixed sleeps — this area already has precedent in the file for paneIsIdle/paneLooksReady polling helpers.
6. Windows/psmux parity. tmux.conf:2 comments "Shared by tmux (macOS/Linux) and psmux (Windows)". Worth confirming remain-on-exit, automatic-rename off, and the pane-died hook are all supported by psmux — if not, these directives could silently no-op (or error) on Windows and Windows users would not get the crash-recovery behavior. The spec doesn't address this and I didn't find a Windows-specific note.
7. automatic-rename off is safe and good. The one test that actually matches the shipped config ("automatic-rename off preserves window names") looks correct. allow-rename off was already set globally at line 13; adding setw -g automatic-rename off closes the gap where tmux auto-derives window titles from the running command.
8. bunfig.toml coverage-ignore for ../.atomic/**. Reasonable — global workflow templates resolved outside project root shouldn't count toward coverage. Non-blocking.
9. Config reload already handled. src/sdk/runtime/tmux.ts:228 calls source-file CONFIG_PATH after new-session, so any new unbinds take effect on the running server — good, no extra plumbing needed once the missing directives are added.
Recommendation
Treat this as Request changes. The research and design are solid; the implementation just didn't fully land. Two concrete options:
- Option A (preferred): add the missing directives (
unbind :,unbind d,unbind c,unbind '"',unbind %,unbind !,unbind n,unbind p,unbind w,unbind L,unbind s,unbind '(',unbind ')',unbind .,unbind C-z,setw -g remain-on-exit on,set-hook -g pane-died "if -F '#{!=:#{pane_dead_status},0}' 'respawn-pane'"), genuinely remove thebind -/bind |splits, verify all four tests pass, and confirm psmux compatibility. - Option B: narrow the PR to just what's implemented (4 unbinds +
automatic-rename off), delete the two tests that rely on missing directives, remove the pane-splitting bullet from the PR description, update the spec, and file a follow-up forremain-on-exit/pane-died/command-prompt lockdown.
Either way, please reconcile the description/spec/tests/config so they agree.
The spec was written pre-implementation with an aggressive lockdown plan (~18 unbinds, remain-on-exit, pane-died hook). Update it to match what was actually shipped: only 4 destructive bindings removed, crash recovery dropped, and pane splitting added. Assistant-model: Claude Code
Code ReviewThanks for the detailed write-up and research docs — the A few issues worth addressing before merge: 🚨 Tests don't match the conf (likely broken/misleading)The PR description says "The
These look like leftovers from the earlier iteration that had Missing test coverage for what the PR actually shipsNone of the four added suites verifies the core change: that Scope creep:
|
Remove tests for unexported functions (isTmuxInstalled, paneIsIdle), inline variable construction tests (launcher script generation), and non-deterministic attemptSubmitRounds edge cases. Assistant-model: Claude Code
Code ReviewThanks for the thorough research and conservative approach. The unbinds themselves are clean and well-scoped, but there's a significant test/config mismatch that needs to be resolved before merging. 🔴 Critical: Tests reference config that was removedThe PR description states:
Yet two of the four new integration test suites explicitly test those removed behaviors against the actual runtime: 1. createSession(REMAIN_SESSION, "echo done && exit 0", "exit-test");
await Bun.sleep(800);
// remain-on-exit keeps the dead pane, so the session must still exist
expect(sessionExists(REMAIN_SESSION)).toBe(true);Without 2. createSession(CRASH_SESSION, "exit 1", "crash-test");
await Bun.sleep(1000);
const result = tmuxRun([\"list-panes\", \"-t\", CRASH_SESSION]);
expect(result.ok).toBe(true);Without the A grep across the repo confirms Fix: either delete these two tests (they validate behavior you intentionally removed) or re-add the directives to 🟡 Missing test coverage for the actual changeNone of the tests verify that const result = tmuxRun([\"list-keys\", \"-T\", \"prefix\"]);
expect(result.stdout).not.toMatch(/^bind-key.* & /m);
expect(result.stdout).not.toMatch(/^bind-key.* x /m);
// etc.That directly protects against accidental regressions. Without it, someone could silently re-add a binding and CI would still pass. 🟡
|
Agent TUIs (Claude Code, OpenCode, Copilot CLI) capture raw keyboard input and consume Ctrl+b before tmux ever sees it, making prefix-based destructive commands effectively inaccessible during normal usage. Assistant-model: Claude Code
Remove tests for remain-on-exit, killWindow with remain-on-exit, automatic-rename, and pane-died hook respawn — these test behaviors that were removed in prior commits. Assistant-model: Claude Code
Code Review — PR #664Thanks for the thorough spec and research docs — the design rationale is well-argued. A few points worth addressing before merge. Blocking / Correctness1. PR description does not match the actual diff (tests). 2. Zero test coverage for the new protection behavior. import { readFileSync } from "node:fs";
const conf = readFileSync("src/sdk/runtime/tmux.conf", "utf8");
test("destructive default keybindings are unbound", () => {
for (const key of [\"&\", \"x\", \",\", \"'\\$'\"]) {
expect(conf).toMatch(new RegExp(\`^unbind \\\\s*\${key.replace(/[\\$]/g, '\\\\\\$')}\`, \"m\"));
}
expect(conf).toMatch(/^setw -g automatic-rename off/m);
});An integration suite (start an Atomic socket, issue Design3. Comment about 4. Command prompt ( 5. Non-unbound creation paths still let users desync the window list. Minor6. 7. Research/spec docs (1,453 lines). What's good
SummaryThe config change itself is small, correct, and defensible. The main issues are (1) the PR description overstates the work (missing tests), (2) the |
Expand the prefix-key comment block to list which bindings are intentionally kept (copy-mode, command prompt, detach, new window, custom splits) and refine the explanation of why Ctrl+b is largely unreachable during agent interaction (raw/alternate screen mode). Assistant-model: Claude Code
Code Review — PR #664Thanks for the thorough work on this — the 🟠 PR description vs. diff discrepancy (please reconcile)The summary says:
But Either the tests got lost before push, or the description needs updating. Given the spec (Section 8.2) calls out "Integration test: Verify the existing workflow e2e test suite still passes" as the main verification path, it's probably worth either adding the suites or tightening the PR summary to match reality. 🟠 Test coverage reduction for still-used functionsTwo functions lost their direct test coverage here, but they're still used in production:
Dropping the The two removed 🟡 Core fix has no automated verificationThe whole point of this PR is that test.if(tmuxAvailable)(\"workflow protection unbinds are applied\", () => {
const keys = Bun.spawnSync([\"tmux\", \"-f\", TMUX_CONF, \"-L\", \"review\", \"list-keys\", \"-T\", \"prefix\"])
.stdout.toString();
expect(keys).not.toMatch(/kill-window/);
expect(keys).not.toMatch(/kill-pane/);
expect(keys).not.toMatch(/rename-window/);
expect(keys).not.toMatch(/rename-session/);
});…would lock in the invariant and catch accidental regressions if someone edits Without this, a future contributor could silently delete 🟢
|
Remove coverage ignore pattern for global workflow templates that was added on this branch but not yet on main. Assistant-model: Claude Code
Code ReviewThanks for the careful, well-documented work here. The conservative scope (4 unbinds + Blocking issues — noneIssues to address1. Live functions had their tests removed (
The PR body labels them "obsolete/flaky," but the smoke tests ("returns boolean", "consistent with getMuxBinary") look cheap and not flaky. If they're genuinely flaky, please share the failure mode — otherwise consider keeping them. The two 2. Misleading inline comments in
Given the PR's stated philosophy ("only block actions that corrupt workflow state"), I'd lean toward the comment fix — splitting panes is non-destructive. 3. PR description references a
The file list contains only the 5 files (research/spec docs, Minor observations4. Trailing blank line added to 5. The defense-in-depth framing is slightly oversold — the spec correctly acknowledges (§5.4) that shell access bypasses keybinding lockdown via 6. Documentation-to-code ratio — 1,453 lines of research/spec docs for a 35-line config change is generous. Not a blocker (the project's CLAUDE.md encourages this), but worth noting for future similar PRs. Code quality & conventions
Bugs / risks
PerformanceNo concerns — config-load-time change, no runtime cost. SecurityGood: removing four destructive default bindings reduces accidental-damage surface. The known limitation (shell-bypass) is correctly documented and is a tmux architectural constraint, not something this PR can fix. Test coverageNet negative — see issue #1. If there's no reason the smoke tests for RecommendationApprove with minor changes — fix the misleading split comment (#2), reconcile the |
Cover the two previously untested helpers with a unit test for isTmuxInstalled (consistency with getMuxBinary) and an integration test for paneIsIdle against a real tmux pane. Assistant-model: Claude Code
Code Review — PR #664The config change itself (4 unbinds + A few points worth addressing before merge: 🟠 No automated guard for the shipped behaviorThe whole point of the PR is that Cheap regression test (pure config content check, no tmux required): import { readFileSync } from \"node:fs\";
test(\"tmux.conf unbinds destructive default keybindings\", () => {
const conf = readFileSync(\"src/sdk/runtime/tmux.conf\", \"utf8\");
expect(conf).toMatch(/^unbind\s+&/m);
expect(conf).toMatch(/^unbind\s+x/m);
expect(conf).toMatch(/^unbind\s+,/m);
expect(conf).toMatch(/^unbind\s+'\\\$'/m);
expect(conf).toMatch(/^setw\s+-g\s+automatic-rename\s+off/m);
});An integration variant using 🟠
|
Summary
Hardens the Atomic tmux session by unbinding four destructive default key bindings and disabling automatic window renaming, preventing accidental corruption of programmatically managed agent sessions.
Key Changes
&(kill-window),x(kill-pane),,(rename-window), and\$(rename-session) — bindings that corrupt workflow state by destroying windows/panes tracked by namesetw -g automatic-rename offto complement the existingallow-rename off, preserving Atomic-assigned window names when commands execute inside panes (preventstmux.selectWindow(name)/tmux.killWindow(name)from targeting wrong windows)|/-split-window bindings to after the workflow-protection section — no functional change, fully availableattemptSubmitRoundsvariants); consolidatedisTmuxInstalledtests and improved test descriptionsresearch/docs/2026-04-16-tmux-destructive-actions-prevention.mddocumenting analysis of 6 protection strategies and rationale for the conservative approachDesign Decision
Out of six strategies evaluated (unbind targeted keys, disable prefix entirely, custom key table, read-only attach, remain-on-exit, pane-died hook), the conservative unbind-only approach was selected:
C-b &C-b xC-b ,selectWindow(name)/killWindow(name)lookupsC-b \$tmuxSessionNamereferences in executorNon-destructive bindings (
C-b [copy-mode,C-b :command prompt,C-b ddetach,C-b cnew window, pane resize) are intentionally kept intact.Notes
-L atomic), leaving the user's default tmux sessions unaffectedC-bis largely unreachable inside Atomic sessions because agent TUIs (Claude Code, OpenCode, Copilot CLI) capture raw keyboard input and consumeCtrl+bbefore tmux sees it — the unbinds are defense-in-depth for the edge case where a user exits an agent back to a bare shell