Coding sessions no longer use tmux, but the names, diagnostics, kill-tmux control and docs all still say they do

[serge-ivo]

The Coder engine stopped using tmux — packages/browser-runner/src/coding/headless.ts:29:

The coding engine — Claude Code driven through its structured stream-json interface, NOT a
scraped tmux TUI … Survives a runner restart without tmux … routes and console keep working
unchanged — only the guts move from tmux to structured JSON.

It spawns a child process (spawn(this.cmdBin, …), :241/:321) and tracks it via
proc.exitCode/signalCode. Nothing in that path calls createSession from coding/tmux.ts.

tmux is still genuinely used — but only by the terminal-operator family (coding/terminal.ts,
server.ts:351-363), i.e. the tmux / Terminal / kitty / iTerm2 Operator agents. Those create real
sessions. Repo Coders do not.

The surface around the coding path was never cleaned up, and it now actively misleads.

What's stale

1. A session name that names nothing. headless.ts:115 still computes
this.sessionName = pags-${clientType}-${id}, which is persisted to coding_sessions.tmux_session
and surfaced through the API and console. On a live instance today: 13 sessions each recording
pags-claude-csess_…, and zero such tmux sessions have ever existed. A user who tries
tmux attach -t pags-claude-csess_… — the obvious thing to do with a name like that — gets
"session not found" and reasonably concludes their engine is broken.

2. Diagnostics measure something structurally always zero. coding_diagnostics returns
tmux: { trackedSessions, orphanedSessions, tmuxTotal, pagsTmuxTotal }. Real output from an
instance whose runner is healthy:

tmux: { trackedSessions: 0, orphanedSessions: [], tmuxTotal: 4, pagsTmuxTotal: 0 }

pagsTmuxTotal: 0 is not a symptom — it can never be anything else for a coding agent. tmuxTotal: 4
counts the user's own unrelated tmux sessions. This is the panel someone opens because something
is wrong, and it points them at a false cause.

3. A "Kill tmux" control that cannot help. POST /:instanceId/coding/kill-tmux (routes/coding.ts:1413)
proxies to the runner's /coding/kill-tmux. For a coding session there is no tmux to kill, so the
diagnostics panel offers a cleanup action that structurally no-ops for the sessions it is shown
beside.

4. The docs describe the old architecture. pags/CLAUDE.md still says "Engine = the actual CLI
running in a tmux pane on the user's machine", "tmux addressed by session name (not :0.0)",
and "The runner reattaches to existing tmux coding sessions on reconnect". The last one is
wrong in a load-bearing way: reattach works by re-spawning with --resume <claudeSessionId> from
~/.claude, which is why it survives a restart without tmux.

5. Stale comments in live code. lib/coding-store.ts:444 explains the driver-claim expiry in
terms of "the RUNNER reports no tmux". The reconciler is fine — trackedIds comes from the runner's
in-memory tracked[] registry (routes/coding.ts:1495-1497), not from tmux — but the comment sends
the next reader down the wrong path. (Verified: not a functional bug.)

Suggested shape

• Drop tmuxSession from the coding-session model, or rename it to what it is (an engine/session
  label). If the column stays for migration reasons, stop surfacing it in the API and console.
• Remove the tmux block from coding_diagnostics for coding agents, or scope it to the
  terminal-operator agents where it means something.
• Retire or re-scope kill-tmux on the coding path.
• Update CLAUDE.md and the published docs to describe the stream-json engine and --resume
  reattach. Docs [docs] Reconcile runtime docs with relay-only pags up #208/[docs] Update Coder docs for runner-node picker, engines, and package paths #211 already cover runtime/Coder doc drift — this belongs with them.

Why bother

This is what made a maintainer (and the product owner) ask "are Coder agents connected to tmux?"
and start debugging in the wrong place. The names, the diagnostics panel and the docs all assert an
architecture the code deliberately replaced.

---

Verified, and the three forks resolved

Every claim above checks out against the code, plus the live-data assertion: this machine has 4 tmux sessions and zero named pags-* — one is tmux-operator-runner, i.e. the operator family, exactly as described.

Two findings that decide the open questions:

Nothing consumes the stale surfaces. No console or coder-web code reads tmuxSession, pagsTmuxTotal, or calls kill-tmux. The only consumer of /coding/diagnostics at all is MCP coding_diagnostics (workers/mcp/src/instance-tools/coding.ts:27), which passes the JSON through. So all three forks lean the same way — remove — and none is a breaking change for a real caller.

kill-tmux is NOT a no-op, contrary to point 3. Its no-args branch calls runner.coding.closeAll() (server.ts:237), which really does close the tracked engine processes. Only the tmux targeting is dead. Retiring the route wholesale would delete the one working "close everything" escape hatch — it needs re-scoping, not removal.

Decisions

1. sessionName → engineLabel, and drop the pags- prefix. The prefix is what makes a user type tmux attach -t pags-claude-…. In the coding path this value addresses nothing — runtime.ts:193/211 only reports it. The persisted column coding_sessions.tmux_session stays (a D1 column rename is a table rewrite for a cosmetic gain); it gets a comment saying it holds an engine label under a legacy name, and stops being surfaced as tmuxSession in API responses.
2. Remove the tmux block from the coding diagnostics rather than scoping it. trackedSessions/orphanedSessions/pagsTmuxTotal are structurally zero for coding agents, and tmuxTotal counts the user's unrelated sessions. The operator agents have their own endpoints and are untouched.
3. Re-scope kill-tmux to what works. Runner keeps the path (an older runner must still answer a newer API — version skew), with the tmux targeting stripped so it just closes tracked coding sessions. The API gains the honest name POST /:instanceId/coding/close-sessions; kill-tmux stays as a deprecated alias since removing a route nothing calls buys nothing.

Also needed, not in the original scope

coding/tmux.ts also hosts ensureRepo (:166, does the git clone) and sanitizeSessionName (:153), both imported by runtime.ts:6 and neither anything to do with tmux. The file cannot simply shrink to nothing; those two move out first.

The docs pointer at the end should not say #208/#211 — those are the two docs tickets whose numbers unrelated commits have been misusing, so it sends the reader to the wrong place.

Acceptance criteria

• No coding session records or reports a pags-* value that looks like a tmux target.
• /coding/diagnostics returns nothing tmux-shaped for a coding agent; the operator agents' tmux endpoints are unchanged and still work.
• "Close all coding sessions" still works, under a name that says so.
• ensureRepo/sanitizeSessionName no longer live in a file named tmux.
• coding-store.ts:444 no longer explains the claim expiry in terms of tmux.
• pags/CLAUDE.md describes the stream-json engine and --resume reattach, not tmux panes.
• Tests cover the label shape and the diagnostics payload.

[serge-ivo]

Confirmed there is no tmux option on the coding path — CodingRuntime.start() (coding/runtime.ts:126) unconditionally constructs new HeadlessSession({…}). No branch, no flag, no env var selects a tmux-backed engine, so this is not a configurable backend that happens to default away from tmux; the alternative implementation is gone.

Two more stale comments to fold into the cleanup, both in coding/runtime.ts and both describing the removed design:

• :9-10 — "The coding runtime: the local 'hands' that hold live tmux coding sessions, the tmux counterpart of the browser runtime's Playwright page management."
• :60 — "…the tmux analogue of…"

Worth stating positively in whatever replaces these, since it is the question a reader actually has: on a Coder you choose the engine (config.codingEngines → the session's launch_command), not a terminal backend. tmux belongs to the terminal-connector agents.

[serge-ivo]

Delivered in ca534f3 — API deployed, CLI 0.4.31 published.

All four decisions from the resolution above shipped:

1. sessionName → engineLabel, formatted <engine>:<id>. The pags- prefix is gone — it was the thing that made tmux attach -t pags-claude-… look like the obvious move. coding_sessions.tmux_session keeps its name (a D1 column rename is a table rewrite for a cosmetic gain) with a comment saying what it actually holds, and is surfaced as engineLabel.
2. The tmux block is out of /coding/diagnostics, replaced by engine: { trackedSessions }. The operator agents' /tmux/* endpoints are untouched.
3. kill-tmux re-scoped, not retired — see the correction above: it was never a no-op. It now closes tracked coding sessions and nothing else, exposed as close-sessions, with the old runner path and API route kept as aliases for version skew.
4. ensureRepo + sanitizeSessionName moved to coding/repo.ts, so the tmux module is only tmux and only the terminal-operator agents import it.

coding-store.ts:444 and the surrounding tmux-framed comments are corrected.

Docs were already done — another session had updated pags/CLAUDE.md to describe the stream-json engine and --resume reattach, citing this issue. I fixed the two lines that my change made stale (the label shape, and kill-tmux in the route list). So the point about #208/#211 is moot; nothing here depends on them.

Verified on a live machine throughout: 4 tmux sessions, zero named pags-*, one being tmux-operator-runner.

2842 tests green.

[serge-ivo]

Two follow-ups filed off this:

• Show which credential a coding session actually used (subscription vs per-token API key) and what the engine really is #248 — make the runtime kind visible per session, so "is this tmux?" is answerable in the UI instead of implied by a vestigial name. Bundled with the credential-visibility ask, since both are "what is my engine actually doing" transparency.
• Decide: should tmux return as a selectable Coder engine backend? (real PTY + attach) #249 — the decision this issue implies but does not make: restore tmux as a selectable backend, or finish removing the naming. Coding sessions no longer use tmux, but the names, diagnostics, kill-tmux control and docs all still say they do #247 assumes the latter; Decide: should tmux return as a selectable Coder engine backend? (real PTY + attach) #249 puts the former on the table with the trade-offs, since the vestigial names are only wrong if tmux is never coming back.