From ffa7fcf8392b1c48817c7cf446b237e9d1528a1f Mon Sep 17 00:00:00 2001 From: Tenggan Zhang <38639187+TeigenZhang@users.noreply.github.com> Date: Tue, 28 Apr 2026 08:11:11 +0800 Subject: [PATCH] fix(tmux-manager): use '|' separator in reconcileSessions (#71) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * fix(tmux-manager): use '|' separator in reconcileSessions Under non-tty execution contexts (launchd on macOS, systemd without TTY), tmux emits '\t' in FORMAT strings as the literal two characters `\` + `t` rather than as a tab. The parser's `line.indexOf('\t')` (a real tab char) therefore never matches, `activeSessions` stays empty, `reconcileSessions` returns `alive: []` / `discovered: []`, and `cleanupStaleSessions()` wipes every entry in `state.json` — even though the underlying tmux sessions are still alive. On the next startup the user sees an empty session list. The bug reproduces reliably when codeman is launched via a user LaunchAgent or a systemd unit without `TTYPath`. Interactive `npm run dev` hides it because tmux's format parser does interpret `\t` when stdout is a TTY. Fix: use `|` as the separator. tmux passes it through verbatim in every environment, and `|` is not a valid tmux session-name character so it cannot collide with the codeman- / claudeman- naming scheme. * test(tmux-manager): cover parsePaneList separator contract Extract the inline pane-list parser from `reconcileSessions` into an exported `parsePaneList()` helper plus `PANE_LIST_SEP` / `PANE_LIST_FORMAT` constants, so the '|' separator contract can be unit-tested directly. The new tests lock in: - Well-formed parsing into name -> pid Map - Empty / blank-line / missing-separator handling - Non-numeric pid and empty-name rejection - A literal `\t` (backslash + t) in the input is NOT treated as a delimiter — guards against the launchd/systemd regression that motivated PR #71. - Splitting on the first separator only. No behavior change in `reconcileSessions`; the body now delegates to the helper. Co-Authored-By: Claude Opus 4.7 (1M context) --------- Co-authored-by: Teigen Co-authored-by: arkon Co-authored-by: Claude Opus 4.7 (1M context) --- src/tmux-manager.ts | 54 ++++++++++++++++++------ test/tmux-manager.test.ts | 89 ++++++++++++++++++++++++++++++++++++--- 2 files changed, 125 insertions(+), 18 deletions(-) diff --git a/src/tmux-manager.ts b/src/tmux-manager.ts index 69542bfe..c16b55ce 100644 --- a/src/tmux-manager.ts +++ b/src/tmux-manager.ts @@ -98,6 +98,44 @@ const LEGACY_MUX_NAME_PATTERN = /^claudeman-[a-f0-9-]+$/; /** Regex to validate tmux pane targets (e.g., "%0", "%1", "0", "1") */ const SAFE_PANE_TARGET_PATTERN = /^(%\d+|\d+)$/; +/** + * Separator used in `tmux list-panes -F` output between session name and pid. + * + * Must NOT be a backslash-escape (e.g. `\t`, `\n`): under non-tty execution + * contexts (launchd on macOS, systemd without TTYPath) tmux can emit such + * escapes as the literal two characters `\` + letter rather than the control + * byte, breaking the parser and causing every tracked session to be classified + * as dead — which wipes state.json on restart. '|' is passed through verbatim + * in every environment and is rejected by tmux's own session-name validation, + * so it cannot appear inside `#{session_name}` and cause a false split. + */ +const PANE_LIST_SEP = '|'; + +/** Format string for `tmux list-panes -F`. Keep in sync with {@link parsePaneList}. */ +const PANE_LIST_FORMAT = `#{session_name}${PANE_LIST_SEP}#{pane_pid}`; + +/** + * Parse the output of `tmux list-panes -a -F '#{session_name}|#{pane_pid}'` + * into a Map of session-name → pane pid. Exported for unit testing. + * + * - Skips empty lines and lines without the separator. + * - Skips entries with a non-numeric pid or empty name. + */ +export function parsePaneList(output: string): Map { + const result = new Map(); + for (const line of output.split('\n')) { + if (!line) continue; + const sep = line.indexOf(PANE_LIST_SEP); + if (sep === -1) continue; + const name = line.slice(0, sep); + const pid = parseInt(line.slice(sep + 1), 10); + if (name && !Number.isNaN(pid)) { + result.set(name, pid); + } + } + return result; +} + /** Characters unsafe in paths — shell metacharacters, quotes, and control chars */ const UNSAFE_PATH_CHARS = /[;&|$`(){}<>'"\n\r]/; @@ -902,23 +940,13 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer { const discovered: string[] = []; // Batch: single tmux call to get all session names + pane PIDs (replaces N per-session subprocess calls) - const activeSessions = new Map(); + let activeSessions = new Map(); try { - const output = execSync("tmux list-panes -a -F '#{session_name}\t#{pane_pid}' 2>/dev/null || true", { + const output = execSync(`tmux list-panes -a -F '${PANE_LIST_FORMAT}' 2>/dev/null || true`, { encoding: 'utf-8', timeout: EXEC_TIMEOUT_MS, }).trim(); - - for (const line of output.split('\n')) { - if (!line) continue; - const sep = line.indexOf('\t'); - if (sep === -1) continue; - const name = line.slice(0, sep); - const pid = parseInt(line.slice(sep + 1), 10); - if (name && !Number.isNaN(pid)) { - activeSessions.set(name, pid); - } - } + activeSessions = parsePaneList(output); } catch (err) { console.error('[TmuxManager] Failed to list tmux panes:', err); } diff --git a/test/tmux-manager.test.ts b/test/tmux-manager.test.ts index b93a207f..105a1a09 100644 --- a/test/tmux-manager.test.ts +++ b/test/tmux-manager.test.ts @@ -8,7 +8,7 @@ */ import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'; -import { TmuxManager } from '../src/tmux-manager.js'; +import { TmuxManager, parsePaneList } from '../src/tmux-manager.js'; import { execSync } from 'node:child_process'; // ============================================================================ @@ -287,13 +287,27 @@ describe('TmuxManager (unit)', () => { }); it('should update respawn config', () => { - const config = { enabled: true, idleTimeoutMs: 5000, updatePrompt: 'test', interStepDelayMs: 1000, sendClear: true, sendInit: true }; + const config = { + enabled: true, + idleTimeoutMs: 5000, + updatePrompt: 'test', + interStepDelayMs: 1000, + sendClear: true, + sendInit: true, + }; manager.updateRespawnConfig('meta-test', config); expect(manager.getSession('meta-test')?.respawnConfig).toEqual(config); }); it('should clear respawn config', () => { - manager.updateRespawnConfig('meta-test', { enabled: true, idleTimeoutMs: 5000, updatePrompt: 'test', interStepDelayMs: 1000, sendClear: true, sendInit: true }); + manager.updateRespawnConfig('meta-test', { + enabled: true, + idleTimeoutMs: 5000, + updatePrompt: 'test', + interStepDelayMs: 1000, + sendClear: true, + sendInit: true, + }); manager.clearRespawnConfig('meta-test'); expect(manager.getSession('meta-test')?.respawnConfig).toBeUndefined(); }); @@ -327,8 +341,8 @@ describe('TmuxManager (unit)', () => { const sessions = manager.getSessions(); expect(sessions).toHaveLength(2); - expect(sessions.map(s => s.sessionId)).toContain('s1'); - expect(sessions.map(s => s.sessionId)).toContain('s2'); + expect(sessions.map((s) => s.sessionId)).toContain('s1'); + expect(sessions.map((s) => s.sessionId)).toContain('s2'); }); }); @@ -342,3 +356,68 @@ describe('TmuxManager (unit)', () => { }); }); +// ============================================================================ +// Parser Tests — locks in the '|' separator contract for `tmux list-panes -F` +// output, guarding against regressions in non-tty execution contexts where +// `\t` in tmux FORMAT strings can be emitted as the literal two characters +// `\` + `t` instead of a tab byte (launchd, systemd without TTYPath, docker +// exec without TTY). See PR #71. +// ============================================================================ + +describe('parsePaneList', () => { + it('parses well-formed output into name → pid', () => { + const out = 'codeman-aaaa|1234\ncodeman-bbbb|5678\nclaudeman-cccc|9999'; + const result = parsePaneList(out); + expect(result.size).toBe(3); + expect(result.get('codeman-aaaa')).toBe(1234); + expect(result.get('codeman-bbbb')).toBe(5678); + expect(result.get('claudeman-cccc')).toBe(9999); + }); + + it('returns an empty map for empty output', () => { + expect(parsePaneList('').size).toBe(0); + }); + + it('skips blank lines', () => { + const result = parsePaneList('\ncodeman-aaaa|100\n\n\ncodeman-bbbb|200\n'); + expect(result.size).toBe(2); + expect(result.get('codeman-aaaa')).toBe(100); + expect(result.get('codeman-bbbb')).toBe(200); + }); + + it('skips lines without the separator', () => { + const result = parsePaneList('codeman-aaaa 1234\ncodeman-bbbb|5678'); + expect(result.size).toBe(1); + expect(result.get('codeman-bbbb')).toBe(5678); + }); + + it('skips lines with a non-numeric pid', () => { + const result = parsePaneList('codeman-aaaa|notapid\ncodeman-bbbb|5678'); + expect(result.size).toBe(1); + expect(result.get('codeman-bbbb')).toBe(5678); + }); + + it('skips lines with an empty session name', () => { + const result = parsePaneList('|1234\ncodeman-bbbb|5678'); + expect(result.size).toBe(1); + expect(result.get('codeman-bbbb')).toBe(5678); + }); + + it('treats a literal backslash-t in input as part of the session name, not a delimiter', () => { + // Reproduces the launchd/systemd regression: under non-tty contexts tmux + // was emitting FORMAT '\t' as the two characters `\` + `t` rather than a + // tab byte. With the '|' separator, such literals must not be silently + // treated as a delimiter — the line is discarded because there is no '|'. + const literalBackslashT = 'codeman-aaaa\\t1234'; + const result = parsePaneList(literalBackslashT); + expect(result.size).toBe(0); + }); + + it('splits on the first separator only', () => { + // Numeric trailing junk after the pid is tolerated by parseInt — proves + // that splitting on the first '|' leaves the pid extractable even if a + // future tmux ever appended extra fields. + const result = parsePaneList('codeman-aaaa|1234|extra-field'); + expect(result.get('codeman-aaaa')).toBe(1234); + }); +});