tmuxes 0.1.8 → 0.1.9

package/server/src/ws/terminalSession.ts

@@ -0,0 +1,207 @@
+import * as pty from 'node-pty';
+import { homedir } from 'node:os';
+import type { WebSocket } from 'ws';
+import type { Target } from '../targets.js';
+import { attachArgv } from '../tmux/builder.js';
+import { resolveExecutable } from '../exe.js';
+import { classifySsh } from './sshState.js';
+import type { ClientControl, ServerControl } from './protocol.js';
+import { log } from '../logger.js';
+
+const HEARTBEAT_MS = 30_000;
+const HIGH_WATER = 1 << 20; // 1 MiB buffered → pause the PTY
+const LOW_WATER = 1 << 18; // 256 KiB → resume
+const KILL_GRACE_MS = 2_000;
+
+/** Owns exactly one PTY for one WebSocket. dispose() is idempotent. */
+export class TerminalSession {
+  private readonly ptyProc: pty.IPty;
+  private disposed = false;
+  private alive = true;
+  private paused = false;
+  private heartbeat?: NodeJS.Timeout;
+  private drainTimer?: NodeJS.Timeout;
+  private killTimer?: NodeJS.Timeout;
+  /** Scan ssh output for failure/prompt states until the link looks healthy. */
+  private sshScanBudget: number;
+
+  constructor(
+    private readonly ws: WebSocket,
+    private readonly target: Target,
+    private readonly session: string,
+    cols: number,
+    rows: number,
+  ) {
+    this.sshScanBudget = target.kind === 'ssh' ? 8192 : 0;
+
+    const { file, args } = attachArgv(target, session);
+    // node-pty on Windows needs a full exe path (no PATH/.exe resolution).
+    this.ptyProc = pty.spawn(resolveExecutable(file), args, {
+      name: 'xterm-256color',
+      cols,
+      rows,
+      cwd: homedir(),
+      env: { ...process.env, TERM: 'xterm-256color' },
+    });
+
+    this.ptyProc.onData((data) => this.onPtyData(data));
+    this.ptyProc.onExit(({ exitCode }) => this.onPtyExit(exitCode));
+
+    this.ws.on('message', (data, isBinary) => this.onClientMessage(data, isBinary));
+    this.ws.on('close', () => this.dispose());
+    this.ws.on('error', () => this.dispose());
+    this.ws.on('pong', () => {
+      this.alive = true;
+    });
+
+    this.heartbeat = setInterval(() => this.tick(), HEARTBEAT_MS);
+
+    this.sendControl({ type: 'ready', target: target.id, session });
+  }
+
+  private onPtyData(data: string): void {
+    if (this.sshScanBudget > 0) {
+      this.sshScanBudget -= data.length;
+      const ssh = classifySsh(data);
+      if (ssh) this.sendControl({ type: 'ssh', state: ssh.state, message: ssh.message });
+    }
+    this.sendBinary(Buffer.from(data, 'utf8'));
+  }
+
+  private onPtyExit(exitCode: number | null): void {
+    this.sendControl({ type: 'exit', code: exitCode });
+    this.closeWs(1000, 'pty exited');
+    this.dispose();
+  }
+
+  private onClientMessage(data: unknown, isBinary: boolean): void {
+    if (this.disposed) return;
+    if (isBinary) {
+      // Raw keystrokes → straight into the PTY.
+      this.ptyProc.write(toBufferString(data));
+      return;
+    }
+    let msg: ClientControl;
+    try {
+      msg = JSON.parse(toBufferString(data)) as ClientControl;
+    } catch {
+      return; // ignore malformed control frames
+    }
+    if (msg.type === 'resize') {
+      const cols = clampDim(msg.cols);
+      const rows = clampDim(msg.rows);
+      if (cols && rows) {
+        try {
+          this.ptyProc.resize(cols, rows);
+        } catch {
+          /* pty may have exited */
+        }
+      }
+    } else if (msg.type === 'ping') {
+      this.sendControl({ type: 'pong' });
+    }
+  }
+
+  private sendBinary(buf: Buffer): void {
+    if (this.disposed || this.ws.readyState !== this.ws.OPEN) return;
+    this.ws.send(buf, { binary: true });
+    if (!this.paused && this.ws.bufferedAmount > HIGH_WATER) {
+      this.paused = true;
+      this.ptyProc.pause();
+      this.drainTimer = setInterval(() => this.checkDrain(), 50);
+    }
+  }
+
+  private checkDrain(): void {
+    if (this.disposed) return;
+    if (this.ws.bufferedAmount < LOW_WATER) {
+      this.paused = false;
+      if (this.drainTimer) clearInterval(this.drainTimer);
+      this.drainTimer = undefined;
+      this.ptyProc.resume();
+    }
+  }
+
+  private sendControl(msg: ServerControl): void {
+    if (this.disposed || this.ws.readyState !== this.ws.OPEN) return;
+    this.ws.send(JSON.stringify(msg), { binary: false });
+  }
+
+  private tick(): void {
+    if (!this.alive) {
+      log.warn(`heartbeat lost for ${this.target.id}/${this.session}, terminating`);
+      try {
+        this.ws.terminate();
+      } catch {
+        /* ignore */
+      }
+      this.dispose();
+      return;
+    }
+    this.alive = false;
+    try {
+      this.ws.ping();
+    } catch {
+      /* ignore */
+    }
+  }
+
+  private closeWs(code: number, reason: string): void {
+    try {
+      if (this.ws.readyState === this.ws.OPEN) this.ws.close(code, reason);
+    } catch {
+      /* ignore */
+    }
+  }
+
+  /** Idempotent teardown — called from pty exit, ws close, and shutdown. */
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+
+    if (this.heartbeat) clearInterval(this.heartbeat);
+    if (this.drainTimer) clearInterval(this.drainTimer);
+
+    try {
+      this.ptyProc.kill(); // SIGHUP → tmux client detaches; session keeps running
+    } catch {
+      /* already gone */
+    }
+    // Force-kill if it lingers.
+    this.killTimer = setTimeout(() => {
+      try {
+        this.ptyProc.kill('SIGKILL');
+      } catch {
+        /* already gone */
+      }
+    }, KILL_GRACE_MS);
+    this.killTimer.unref?.();
+
+    this.closeWs(1000, 'disposed');
+    registry.delete(this);
+  }
+}
+
+function toBufferString(data: unknown): string {
+  if (typeof data === 'string') return data;
+  if (Buffer.isBuffer(data)) return data.toString('utf8');
+  if (Array.isArray(data)) return Buffer.concat(data).toString('utf8');
+  if (data instanceof ArrayBuffer) return Buffer.from(data).toString('utf8');
+  return String(data);
+}
+
+function clampDim(n: unknown): number | null {
+  if (typeof n !== 'number' || !Number.isInteger(n) || n < 1 || n > 1000) return null;
+  return n;
+}
+
+/** All live sessions, so the process can tear them down on shutdown. */
+export const registry = new Set<TerminalSession>();
+
+export function track(s: TerminalSession): void {
+  registry.add(s);
+}
+
+export function disposeAll(): void {
+  for (const s of [...registry]) s.dispose();
+}

package/server/src/ws/wsServer.ts

@@ -0,0 +1,153 @@
+import type { Server as HttpServer, IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+import { WebSocketServer, type WebSocket } from 'ws';
+import { config } from '../config.js';
+import { getTarget, isValidTargetId, type Target } from '../targets.js';
+import { isValidSessionName, isValidDimension } from '../validate.js';
+import { TerminalSession, track } from './terminalSession.js';
+import { winShell, type ShellClient } from '../winshell/manager.js';
+import type { ClientControl } from './protocol.js';
+import { log } from '../logger.js';
+
+const HEARTBEAT_MS = 30_000;
+
+function reject(socket: Duplex, status: number, message: string): void {
+  socket.write(`HTTP/1.1 ${status} ${message}\r\nConnection: close\r\n\r\n`);
+  socket.destroy();
+}
+
+function rawToString(data: unknown): string {
+  if (typeof data === 'string') return data;
+  if (Buffer.isBuffer(data)) return data.toString('utf8');
+  if (Array.isArray(data)) return Buffer.concat(data as Buffer[]).toString('utf8');
+  if (data instanceof ArrayBuffer) return Buffer.from(data).toString('utf8');
+  return String(data);
+}
+
+let nextClientId = 1;
+
+/** Attach a WS to a native shell session (one persistent pty, many clients). */
+function attachWinShell(ws: WebSocket, target: Target, session: string, cols: number, rows: number): void {
+  const client: ShellClient = {
+    id: nextClientId++,
+    sendBinary: (buf) => {
+      if (ws.readyState === ws.OPEN) ws.send(buf, { binary: true });
+    },
+    sendControl: (msg) => {
+      if (ws.readyState === ws.OPEN) ws.send(JSON.stringify(msg), { binary: false });
+    },
+    isOpen: () => ws.readyState === ws.OPEN,
+    close: (code, reason) => {
+      try {
+        ws.close(code, reason);
+      } catch {
+        /* ignore */
+      }
+    },
+  };
+
+  let shellSession;
+  try {
+    shellSession = winShell.attachOrCreate(session, cols, rows, client);
+  } catch (e) {
+    client.sendControl({ type: 'error', message: e instanceof Error ? e.message : 'failed to start shell' });
+    client.close(1011, 'shell error');
+    return;
+  }
+  client.sendControl({ type: 'ready', target: target.id, session });
+
+  ws.on('message', (data, isBinary) => {
+    if (isBinary) {
+      shellSession.write(rawToString(data));
+      return;
+    }
+    let msg: ClientControl;
+    try {
+      msg = JSON.parse(rawToString(data)) as ClientControl;
+    } catch {
+      return;
+    }
+    if (msg.type === 'resize' && isValidDimension(msg.cols) && isValidDimension(msg.rows)) {
+      shellSession.resize(msg.cols, msg.rows);
+    } else if (msg.type === 'ping') {
+      client.sendControl({ type: 'pong' });
+    }
+  });
+
+  let alive = true;
+  ws.on('pong', () => {
+    alive = true;
+  });
+  const hb = setInterval(() => {
+    if (!alive) {
+      try {
+        ws.terminate();
+      } catch {
+        /* ignore */
+      }
+      return;
+    }
+    alive = false;
+    try {
+      ws.ping();
+    } catch {
+      /* ignore */
+    }
+  }, HEARTBEAT_MS);
+
+  const cleanup = () => {
+    clearInterval(hb);
+    shellSession.detach(client); // pty stays alive — persistence across reconnects
+  };
+  ws.on('close', cleanup);
+  ws.on('error', cleanup);
+}
+
+/** Attach the single /ws interactive-attach endpoint to the HTTP server. */
+export function attachWebSocket(server: HttpServer): void {
+  const wss = new WebSocketServer({ noServer: true });
+
+  server.on('upgrade', (req: IncomingMessage, socket: Duplex, head: Buffer) => {
+    let url: URL;
+    try {
+      url = new URL(req.url ?? '', `http://${req.headers.host ?? 'localhost'}`);
+    } catch {
+      reject(socket, 400, 'Bad Request');
+      return;
+    }
+
+    if (url.pathname !== '/ws') {
+      reject(socket, 404, 'Not Found');
+      return;
+    }
+
+    // The WS upgrade bypasses Express middleware — enforce Origin here.
+    if (!config.isAllowedOrigin(req.headers.origin)) {
+      log.warn(`rejected WS upgrade from disallowed origin: ${req.headers.origin}`);
+      reject(socket, 403, 'Forbidden');
+      return;
+    }
+
+    const targetId = url.searchParams.get('target') ?? '';
+    const session = url.searchParams.get('session') ?? '';
+    if (!isValidTargetId(targetId)) return reject(socket, 400, 'Bad Request');
+    const target = getTarget(targetId);
+    if (!target) return reject(socket, 404, 'Not Found');
+    if (!isValidSessionName(session)) return reject(socket, 400, 'Bad Request');
+
+    const colsRaw = Number(url.searchParams.get('cols'));
+    const rowsRaw = Number(url.searchParams.get('rows'));
+    const cols = isValidDimension(colsRaw) ? colsRaw : 80;
+    const rows = isValidDimension(rowsRaw) ? rowsRaw : 24;
+
+    wss.handleUpgrade(req, socket, head, (ws) => {
+      log.info(`attach ${target.id}/${session} (${cols}x${rows})`);
+      if (target.kind === 'winlocal') {
+        attachWinShell(ws, target, session, cols, rows);
+        return;
+      }
+      const ts = new TerminalSession(ws, target, session, cols, rows);
+      track(ts);
+    });
+  });
+}

package/server/src/wsl.ts

@@ -0,0 +1,38 @@
+import { runCommand } from './exec.js';
+import { log } from './logger.js';
+
+/** Distros that exist for the container runtime, never for interactive use. */
+const SYSTEM_DISTROS = /^docker-desktop(-data)?$/i;
+
+const NUL = 0;
+const BOM = 0xfeff;
+
+/**
+ * Enumerate installed WSL distros (Windows only). `wsl.exe -l -q` prints names
+ * one per line in UTF-16LE (with a BOM), so we decode accordingly.
+ */
+export async function listWslDistros(): Promise<string[]> {
+  const r = await runCommand('wsl.exe', ['-l', '-q'], { encoding: 'utf16le', timeoutMs: 8000 });
+  if (r.code !== 0) {
+    if (r.stdout.trim() || r.stderr.trim()) {
+      log.warn(`wsl.exe -l -q failed: ${(r.stderr || r.stdout).trim().split('\n')[0]}`);
+    }
+    return [];
+  }
+  return parseWslList(r.stdout);
+}
+
+/** Parse `wsl.exe -l -q` decoded output into clean distro names. */
+export function parseWslList(stdout: string): string[] {
+  // Drop NULs / BOM via code point so the source stays pure ASCII.
+  const cleaned = Array.from(stdout)
+    .filter((ch) => {
+      const c = ch.charCodeAt(0);
+      return c !== NUL && c !== BOM;
+    })
+    .join('');
+  return cleaned
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((name) => name.length > 0 && !SYSTEM_DISTROS.test(name));
+}

package/server/test/agentHooks.test.ts

@@ -0,0 +1,66 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { augmentAgentCommand, detectAgentKind } from '../src/agentHooks.js';
+
+afterEach(() => {
+  delete process.env.TMUXES_NO_AUTOHOOK;
+});
+
+describe('detectAgentKind', () => {
+  it('recognizes Claude Code and Codex commands', () => {
+    expect(detectAgentKind('claude')).toBe('claude');
+    expect(detectAgentKind('codex')).toBe('codex');
+  });
+
+  it('ignores non-agent commands, including the POSIX cc compiler, and the opt-out flag', () => {
+    expect(detectAgentKind('bash')).toBeUndefined();
+    expect(detectAgentKind('cc')).toBeUndefined();
+    process.env.TMUXES_NO_AUTOHOOK = '1';
+    expect(detectAgentKind('codex')).toBeUndefined();
+  });
+});
+
+describe('augmentAgentCommand', () => {
+  it('adds running, decision, done, and error hooks to Claude Code', () => {
+    const out = augmentAgentCommand('claude --model opus "do x"');
+    expect(out.kind).toBe('claude');
+    expect(out.command).toMatch(/^claude --settings '.*' --model opus "do x"$/);
+    expect(out.command).toContain('"UserPromptSubmit"');
+    expect(out.command).toContain('"PreToolUse"');
+    expect(out.command).toContain('"PostToolUse"');
+    expect(out.command).toContain('"PermissionRequest"');
+    expect(out.command).toContain('"Notification"');
+    expect(out.command).toContain('"Stop"');
+    expect(out.command).toContain('@tmuxes_agent claude:running::UserPromptSubmit:$(date +%s).$$');
+    expect(out.command).toContain('@tmuxes_agent claude:waiting:decision:PermissionRequest:$(date +%s).$$');
+    expect(out.command).toContain('@tmuxes_agent claude:idle:done:Stop:$(date +%s).$$');
+    expect(out.command).toContain('@tmuxes_agent claude:idle:error:StopFailure:$(date +%s).$$');
+  });
+
+  it('produces valid JSON for Claude settings', () => {
+    const out = augmentAgentCommand('claude');
+    const json = out.command.match(/--settings '(.*)'$/)?.[1];
+    expect(json).toBeTruthy();
+    const parsed = JSON.parse(json!);
+    expect(parsed.hooks.PermissionRequest[0].hooks[0].command).toContain('decision');
+    expect(parsed.hooks.Stop[0].hooks[0].command).toContain('done');
+    expect(parsed.hooks.StopFailure[0].hooks[0].command).toContain('error');
+  });
+
+  it('adds lifecycle hook config overrides to Codex', () => {
+    const out = augmentAgentCommand('codex "fix the bug"');
+    expect(out.kind).toBe('codex');
+    expect(out.command).toMatch(/^codex -c 'hooks\.UserPromptSubmit=.*' -c 'hooks\.PreToolUse=.*' /);
+    expect(out.command.endsWith(' "fix the bug"')).toBe(true);
+    expect(out.command).toContain('hooks.PermissionRequest');
+    expect(out.command).toContain('hooks.Stop');
+    expect(out.command).toContain('@tmuxes_agent codex:running::PreToolUse:$(date +%s).$$');
+    expect(out.command).toContain('@tmuxes_agent codex:waiting:decision:PermissionRequest:$(date +%s).$$');
+    expect(out.command).toContain('@tmuxes_agent codex:idle:done:Stop:$(date +%s).$$');
+  });
+
+  it('leaves non-agent or disabled commands untouched', () => {
+    expect(augmentAgentCommand('bash')).toEqual({ command: 'bash' });
+    process.env.TMUXES_NO_AUTOHOOK = 'true';
+    expect(augmentAgentCommand('codex "x"')).toEqual({ command: 'codex "x"' });
+  });
+});

package/server/test/agentOutput.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import { classifyAgentTerminalError } from '../src/agentOutput.js';
+
+describe('classifyAgentTerminalError', () => {
+  it('detects Codex stream disconnects that do not emit a stop hook', () => {
+    const text =
+      'stream disconnected before completion: error sending request for url (https://chatgpt.com/backend-api/codex/responses)';
+    expect(classifyAgentTerminalError(text, 'codex')).toBe('CodexStreamDisconnected');
+  });
+
+  it('handles wrapped or styled terminal output', () => {
+    const text =
+      '\u001b[31mstream disconnected before completion:\u001b[0m\nerror sending request for url (https://chatgpt.com/backend-api/codex/responses)';
+    expect(classifyAgentTerminalError(text, 'codex')).toBe('CodexStreamDisconnected');
+  });
+
+  it('does not apply Codex-specific URL matching to Claude', () => {
+    const text =
+      'stream disconnected before completion: error sending request for url (https://chatgpt.com/backend-api/codex/responses)';
+    expect(classifyAgentTerminalError(text, 'claude')).toBe('StreamDisconnected');
+  });
+
+  it('ignores ordinary terminal output', () => {
+    expect(classifyAgentTerminalError('building project\nall tests passed', 'codex')).toBeUndefined();
+  });
+});

package/server/test/agentState.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+import { agentInitialValue, agentValue, parseAgentValue } from '../src/agentState.js';
+
+describe('agent state values', () => {
+  it('initializes a launched agent without a notification reason', () => {
+    const parsed = parseAgentValue(agentInitialValue('codex'));
+    expect(parsed).toMatchObject({
+      agentKind: 'codex',
+      agentState: 'idle',
+      agentEvent: 'launch',
+    });
+    expect(parsed?.attentionReason).toBeUndefined();
+  });
+
+  it('parses abnormal stop notifications', () => {
+    expect(parseAgentValue(agentValue('codex', 'idle', 'error', 'CodexStreamDisconnected', '42'))).toMatchObject({
+      agentKind: 'codex',
+      agentState: 'idle',
+      attentionReason: 'error',
+      agentEvent: 'CodexStreamDisconnected',
+      agentNonce: '42',
+    });
+  });
+});

package/server/test/builder.test.ts

@@ -0,0 +1,162 @@
+import { describe, it, expect } from 'vitest';
+import { homedir } from 'node:os';
+import {
+  sshQuote,
+  localTmux,
+  remoteTmux,
+  wslTmux,
+  managementArgv,
+  attachArgv,
+  newSessionArgv,
+} from '../src/tmux/builder.js';
+import type { Target } from '../src/targets.js';
+
+const local: Target = { id: 'local', kind: 'local', label: 'Local' };
+const sshFull: Target = { id: 'env-x', kind: 'ssh', label: 'alice@web1:2222', host: 'web1', user: 'alice', port: 2222 };
+const sshAlias: Target = { id: 'cfg-devbox', kind: 'ssh', label: 'devbox', host: 'devbox' };
+const wsl: Target = { id: 'wsl-Ubuntu', kind: 'wsl', label: 'Ubuntu', distro: 'Ubuntu' };
+const isWindows = process.platform === 'win32';
+
+function expectConnectionSharing(argv: string[]): void {
+  if (isWindows) {
+    expect(argv).not.toContain('ControlMaster=auto');
+    expect(argv).not.toContain('ControlPersist=yes');
+    expect(argv.some((arg) => arg.startsWith('ControlPath='))).toBe(false);
+    return;
+  }
+
+  expect(argv).toContain('ControlMaster=auto');
+  expect(argv).toContain('ControlPersist=yes');
+  expect(argv.some((arg) => arg.startsWith('ControlPath='))).toBe(true);
+}
+
+describe('sshQuote', () => {
+  it('single-quotes and escapes embedded quotes', () => {
+    expect(sshQuote('plain')).toBe(`'plain'`);
+    expect(sshQuote(`it's`)).toBe(`'it'\\''s'`);
+  });
+});
+
+describe('localTmux', () => {
+  it('prefixes tmux with zero quoting', () => {
+    expect(localTmux(['list-sessions', '-F', 'x'])).toEqual(['tmux', 'list-sessions', '-F', 'x']);
+  });
+});
+
+describe('remoteTmux management (tty:false)', () => {
+  it('uses BatchMode, ConnectTimeout, connection sharing, port, and quotes remote args', () => {
+    const argv = remoteTmux(sshFull, ['list-sessions', '-F', 'a b'], { tty: false });
+    expect(argv.slice(0, 5)).toEqual(['ssh', '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=8']);
+    expectConnectionSharing(argv);
+    expect(argv).toContain('-p');
+    expect(argv).toContain('2222');
+    expect(argv).toContain('alice@web1');
+    expect(argv.slice(-4)).toEqual(['tmux', `'list-sessions'`, `'-F'`, `'a b'`]);
+  });
+  it('uses the bare alias when no user/port', () => {
+    const argv = remoteTmux(sshAlias, ['kill-session', '-t', 'work'], { tty: false });
+    expect(argv).toContain('devbox');
+    expect(argv).not.toContain('-p');
+    expect(argv[argv.length - 1]).toBe(`'work'`);
+  });
+  it('can disable connection sharing for a one-shot reconnect attempt', () => {
+    const argv = remoteTmux(sshAlias, ['list-sessions'], { tty: false, multiplex: false });
+    expect(argv).toContain('ControlMaster=no');
+    expect(argv).not.toContain('ControlMaster=auto');
+    expect(argv).not.toContain('ControlPersist=yes');
+    expect(argv.some((arg) => arg.startsWith('ControlPath='))).toBe(false);
+  });
+});
+
+describe('remoteTmux interactive (tty:true)', () => {
+  it('forces a PTY with -tt, shares the ssh connection, and does not quote args', () => {
+    const argv = remoteTmux(sshFull, ['new-session', '-A', '-s', 'work'], { tty: true });
+    expect(argv).toContain('-tt');
+    expectConnectionSharing(argv);
+    expect(argv.some((arg) => arg.startsWith('ServerAliveInterval='))).toBe(false);
+    expect(argv.slice(-4)).toEqual(['new-session', '-A', '-s', 'work']);
+  });
+});
+
+describe('wslTmux', () => {
+  it('management runs tmux directly in the distro via wsl.exe -- (no shell)', () => {
+    expect(wslTmux('Ubuntu', ['list-sessions', '-F', 'x'], { tty: false })).toEqual([
+      'wsl.exe',
+      '-d',
+      'Ubuntu',
+      '--exec',
+      'tmux',
+      'list-sessions',
+      '-F',
+      'x',
+    ]);
+  });
+  it('interactive sets TERM via env since WSL does not inherit it', () => {
+    expect(wslTmux('Ubuntu', ['new-session', '-A', '-s', 'work'], { tty: true })).toEqual([
+      'wsl.exe',
+      '-d',
+      'Ubuntu',
+      '--exec',
+      'env',
+      'TERM=xterm-256color',
+      'tmux',
+      'new-session',
+      '-A',
+      '-s',
+      'work',
+    ]);
+  });
+});
+
+describe('managementArgv / attachArgv', () => {
+  it('splits file and args for local', () => {
+    expect(managementArgv(local, ['list-sessions'])).toEqual({ file: 'tmux', args: ['list-sessions'] });
+  });
+  it('local attach uses new-session -A without -d', () => {
+    const { file, args } = attachArgv(local, 'work');
+    expect(file).toBe('tmux');
+    expect(args).toEqual(['new-session', '-A', '-s', 'work']);
+    expect(args).not.toContain('-d');
+  });
+  it('ssh attach goes through ssh -tt', () => {
+    const { file, args } = attachArgv(sshAlias, 'work');
+    expect(file).toBe('ssh');
+    expect(args).toContain('-tt');
+    expect(args.slice(-4)).toEqual(['new-session', '-A', '-s', 'work']);
+  });
+  it('wsl management goes through wsl.exe', () => {
+    expect(managementArgv(wsl, ['list-sessions'])).toEqual({
+      file: 'wsl.exe',
+      args: ['-d', 'Ubuntu', '--exec', 'tmux', 'list-sessions'],
+    });
+  });
+  it('wsl attach goes through wsl.exe with env TERM', () => {
+    const { file, args } = attachArgv(wsl, 'work');
+    expect(file).toBe('wsl.exe');
+    expect(args.slice(0, 5)).toEqual(['-d', 'Ubuntu', '--exec', 'env', 'TERM=xterm-256color']);
+    expect(args.slice(-4)).toEqual(['new-session', '-A', '-s', 'work']);
+  });
+});
+
+describe('newSessionArgv (always starts in HOME)', () => {
+  const sub = ['new-session', '-d', '-s', 'work'];
+  it('local appends tmux -c <homedir>', () => {
+    expect(newSessionArgv(local, sub)).toEqual({
+      file: 'tmux',
+      args: ['new-session', '-d', '-s', 'work', '-c', homedir()],
+    });
+  });
+  it('wsl uses wsl --cd ~ (distro home), no tmux -c', () => {
+    expect(newSessionArgv(wsl, sub)).toEqual({
+      file: 'wsl.exe',
+      args: ['-d', 'Ubuntu', '--cd', '~', '--exec', 'tmux', 'new-session', '-d', '-s', 'work'],
+    });
+  });
+  it('ssh relies on the remote $HOME default (no --cd / -c)', () => {
+    const { file, args } = newSessionArgv(sshAlias, sub);
+    expect(file).toBe('ssh');
+    expect(args).not.toContain('--cd');
+    expect(args).not.toContain('-c');
+    expect(args.slice(-4)).toEqual([`'new-session'`, `'-d'`, `'-s'`, `'work'`]);
+  });
+});