Skip to content

fix(tmux): see an exited agent on tmux 3.8, which blanks a dead pane's pid - #840

Draft
kkalisz wants to merge 1 commit into
Ark0N:masterfrom
kkalisz:fix/dead-pane-blank-pid
Draft

kkalisz wants to merge 1 commit into
Ark0N:masterfrom
kkalisz:fix/dead-pane-blank-pid

Conversation

@kkalisz

@kkalisz kkalisz commented Nov 19, 2026

Copy link
Copy Markdown

Problem

On tmux 3.8, a session whose agent exited cleanly (/exit, Ctrl+C twice) is never seen as exited. It stays on the board as idle with paneExit: null, and the clean-exit sweep from #446 never closes it. Attaching to it shows only tmux's Pane is dead (status 0, …).

The reason: once a pane's program has exited, tmux 3.8 prints #{pane_pid} blank. The comments around the pane watcher say its behaviour was measured on tmux 3.2a, which still reported the pid there. parsePaneRows() skips any row whose pid is not a number:

const pid = parseInt(fields[1] ?? '', 10);
if (!sessionName || Number.isNaN(pid)) continue;

So the one row that carries the exit is thrown away before derivePaneExits() sees it.

Seen on a real install (Codeman 1.51.0, macOS, tmux 3.8), with the watcher's own format:

$ tmux -L codeman list-panes -a -F '#{session_name}|#{pane_pid}|#{pane_dead}|#{pane_dead_status}|#{pane_dead_signal}|#{pane_current_path}'
codeman-55ad9fd1||1|0||

GET /api/sessions still showed that session as "status": "idle", "paneExit": null minutes later.

The same rows also feed reconcileSessions(), so there is a second effect at server start. A tracked session whose only pane is dead is missing from the active map, so it is reported dead and its record is deleted. Its tmux session stays on the socket, and the rediscovery loop skips it for the same reason, so nothing ever lists it again.

Fix

All in src/tmux-manager.ts:

  • parsePaneRows(): pid is optional on a dead row. A row with no pid is kept when #{pane_dead} is 1 and still skipped otherwise, since a live pane with no pid is a bad read.
  • Exit identity: applyPaneExits() used the pane pid to tell "the same dead pane, read again" from "a second command in the same pane that also exited the same way". With the pid blank, that would treat every exit as the same one. PANE_LIST_FORMAT now also reads #{pane_dead_time} (inserted before #{pane_current_path}, which has to stay last), and sameExit compares it next to the pid. tmux stamps it once per exit, so two reads of one exit still count as 2 for the sweep, and a hand-run respawn-pane whose command exits 0 again starts a new observation. On a tmux without the variable the field is empty and the pid works as before.
  • reconcileSessions(): active holds every session on the socket, with its pid when tmux printed one. A tracked session with a dead pane stays alive and keeps its last known pid, which is what tmux reported before 3.8. An untracked codeman-* session with no pid is still not rediscovered: a made-up pid would reach killSession()'s process-tree walk. That matches what happens today.

docs/architecture-invariants.md (the paneExit section) records the tmux 3.8 behaviour next to the existing tmux 3.2a measurements.

Tests

  • parsePaneRows: a dead pane with a blank pid is kept with its status and exit time; a live pane with a blank pid is still skipped; the exit time is read, and is undefined while the pane runs.
  • derivePaneExits: a clean exit is reported from a dead pane with a blank pid.
  • Pane-exit bookkeeping: with no pid, repeated reads of one exit count up to 2; a new exit time starts the count again.
  • reconcileSessions: a tracked session whose only pane is dead with no pid stays alive and keeps its pid; an untracked one is not rediscovered.
  • The existing fixtures in test/tmux-manager.test.ts and test/pane-cwd-tracking.test.ts that include a path get one more empty field for the exit time. That change is mechanical and every assertion is unchanged.

The new parser, derive, bookkeeping and tracked-session tests fail on master and pass with the fix. The rediscovery test passes on both, since it pins the current behaviour. I also checked the parser against a real tmux 3.8 dead pane: codeman-abcd9999||1|0||1795097464| parses to {dead: true, exitStatus: 0, deadTime: 1795097464}, and derivePaneExits() reports the clean exit.

npm run typecheck, eslint and prettier --check pass. Full vitest run: 17071 of 17140 pass. The 69 failures are in 20 files unrelated to tmux (git, cron, remote files, folder routes and so on), and the same 69 fail on master (e99b42c) on this machine.

Follows up #446.

🤖 Generated with Claude Code

…s pid

tmux 3.8 prints #{pane_pid} blank once a pane's program has exited.
parsePaneRows() skipped any row without a numeric pid, so the watcher
never saw an exited agent: the session stayed idle with no paneExit and
the clean-exit sweep (Ark0N#446) never closed it. reconcileSessions() read the
same rows, so at server start such a session's record was dropped while
its tmux session stayed on the socket.

Keep a dead row with no pid (a live one is still a bad read), tell one
exit from the next by #{pane_dead_time} next to the pid, and keep a
tracked session with a dead pane alive with its last known pid. An
untracked one is still not rediscovered: a made-up pid would reach
killSession()'s process-tree walk.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant