COD-107 remote SSH: custom port + advanced connection options (escape hatch)

The Remote case form could only reach port-22, default-identity, directly
SSH-able hosts. Add an escape-hatch set of SSH connection options so Codeman
can reach a host like aa-desktop (custom port 2222, ed25519 identity, cloudflared
SOCKS5 ProxyCommand) the way ssh-aa-desktop does — without shelling out to that
wrapper.

- Model (types/session.ts): new optional RemoteSshOptions (identityFile,
  socksProxy, jumpHost, extraSshOptions) on RemoteHost AND SessionRemote; all
  absent = today's behavior. toSessionRemote() carries them case->session.
- Shared buildSshConnectionArgs(remote) in remote-hosts.ts: pure, exported,
  ordered ssh connection tokens (-o BatchMode=yes, -p, -i <abs identity with
  ~/$HOME expanded + shellescaped>, -J, -o ProxyCommand=nc -X 5 -x <socks>
  %h %p emitted as ONE shellescaped token so %h %p reach ssh literally, then
  each extraSshOptions -o). Both buildRemoteLaunchCommand (tmux-manager.ts) and
  buildRemoteTmuxCheckCommand now use it, so the prereq probe and the real
  launch connect identically. checkRemoteTmuxAvailable widened to accept the
  options (callers already pass the full host).
- Validation (schemas.ts): identityFile (no newline/NUL), socksProxy
  (host:port), jumpHost (no shell metachars), extraSshOptions (KEY=VALUE,
  reject newline/NUL/backtick/$() — defense-in-depth on operator-entered config.
- UI (index.html + session-ui.js): SSH Port field + collapsible "Advanced SSH"
  section (identity, SOCKS proxy, jump host, extra -o options one per line);
  wired into the remote-host create payload.

Empty-options remotes emit byte-identical ssh to before (pinned by test).

Tests: test/remote-ssh-options.test.ts (buildSshConnectionArgs +
buildRemoteLaunchCommand + buildRemoteTmuxCheckCommand for the aa-desktop set,
escaping/%h %p/identity-~ expansion, byte-identical back-compat); case-routes
schema tests (advanced options round-trip; malformed extraSshOptions/socksProxy
rejected). tsc/eslint/frontend-syntax/prettier/build clean.

Acceptance (real remote, no wrapper): the emitted command connected to
aa-desktop through the cloudflared SOCKS proxy and created a durable remote
tmux session (verified independently via ssh-aa-desktop: CONNECTED_NO_WRAPPER,
STILL_ALIVE_AFTER_DETACH); checkRemoteTmuxAvailable over the proxy returned
{ok:true, tmuxPath:/usr/local/bin/tmux}; test session cleaned up.

test/remote-ssh-options.test.ts

@@ -0,0 +1,172 @@
+/**
+ * @fileoverview COD-107 — Remote-host SSH: custom port + advanced connection options.
+ *
+ * Unit tests for the shared, pure `buildSshConnectionArgs(remote)` and its two
+ * consumers (`buildRemoteLaunchCommand`, `buildRemoteTmuxCheckCommand`). The
+ * acceptance target is the aa-desktop option set (custom port 2222, ed25519
+ * identity under `~`, a cloudflared SOCKS5 ProxyCommand, plus an arbitrary
+ * `-o` escape-hatch option) — the same connection `~/repos/claude-config/bin/
+ * ssh-aa-desktop` makes, WITHOUT shelling out to that wrapper.
+ *
+ * Critical, easy-to-break invariants pinned here:
+ *  - `%h %p` in the ProxyCommand reach ssh LITERALLY (one shellescaped
+ *    `-o ProxyCommand=…` token; the local shell must not expand/mangle them).
+ *  - a leading `~`/`$HOME` in `identityFile` is expanded to an absolute path at
+ *    build time (ssh does NOT expand `~` in `-i`), then shellescaped.
+ *  - empty options ⇒ byte-identical ssh to today (full back-compat).
+ *
+ * Pure command-string construction; no real tmux, no ssh. Port: N/A.
+ */
+
+import { homedir } from 'node:os';
+import { describe, it, expect } from 'vitest';
+import { buildSshConnectionArgs, buildRemoteTmuxCheckCommand, remoteSshTarget } from '../src/remote-hosts.js';
+import { buildRemoteLaunchCommand } from '../src/tmux-manager.js';
+import type { SessionRemote } from '../src/types.js';
+
+const HOME = homedir();
+
+const baseRemote: SessionRemote = {
+  hostId: 'gpu-box',
+  label: 'GPU Box',
+  host: '10.0.0.42',
+  username: 'ubuntu',
+  remotePath: '/home/ubuntu/work',
+};
+
+// The acceptance host: aa-desktop reached over the cloudflared SOCKS5 proxy.
+const aaDesktop: SessionRemote = {
+  hostId: 'aa-desktop',
+  label: 'aa-desktop',
+  host: '192.168.55.170',
+  username: 'aakht',
+  port: 2222,
+  remotePath: '/tmp',
+  identityFile: '~/.ssh/remote_ed25519',
+  socksProxy: '127.0.0.1:1080',
+  extraSshOptions: ['StrictHostKeyChecking=accept-new'],
+  commands: { shell: 'exec bash -l' },
+};
+
+const SESSION_ID = 'cod107chk';
+
+describe('COD-107 buildSshConnectionArgs — shared ssh connection tokens', () => {
+  it('always leads with -o BatchMode=yes', () => {
+    expect(buildSshConnectionArgs(baseRemote)).toEqual(['ssh', '-o BatchMode=yes']);
+  });
+
+  it('emits the full aa-desktop option set in order with escaping + %h %p intact', () => {
+    const args = buildSshConnectionArgs(aaDesktop);
+    const joined = args.join(' ');
+
+    // -p before -i before the proxy -o; identity ~ expanded absolute, then escaped.
+    expect(joined).toContain('-o BatchMode=yes');
+    expect(joined).toContain('-p 2222');
+    expect(joined).toContain(`-i '${HOME}/.ssh/remote_ed25519'`);
+    // No literal tilde survives into the -i token.
+    expect(joined).not.toContain('-i ~');
+    expect(joined).not.toContain("-i '~");
+
+    // The whole ProxyCommand (with its spaces and %h %p) is ONE shellescaped -o token.
+    expect(joined).toContain("-o 'ProxyCommand=nc -X 5 -x 127.0.0.1:1080 %h %p'");
+    // %h %p must survive verbatim — they are ssh tokens, not shell tokens.
+    expect(joined).toContain('%h %p');
+
+    // The escape-hatch extra option, shellescaped.
+    expect(joined).toContain("-o 'StrictHostKeyChecking=accept-new'");
+
+    // Ordering: BatchMode -> port -> identity -> ProxyCommand -> extras.
+    const idxBatch = joined.indexOf('BatchMode=yes');
+    const idxPort = joined.indexOf('-p 2222');
+    const idxIdentity = joined.indexOf('-i ');
+    const idxProxy = joined.indexOf('ProxyCommand=');
+    const idxExtra = joined.indexOf('StrictHostKeyChecking');
+    expect(idxBatch).toBeLessThan(idxPort);
+    expect(idxPort).toBeLessThan(idxIdentity);
+    expect(idxIdentity).toBeLessThan(idxProxy);
+    expect(idxProxy).toBeLessThan(idxExtra);
+  });
+
+  it('supports an explicit -J jump host', () => {
+    const args = buildSshConnectionArgs({ ...baseRemote, jumpHost: 'bastion@10.0.0.1:22' });
+    expect(args.join(' ')).toContain('-J bastion@10.0.0.1:22');
+  });
+
+  it('expands a $HOME-prefixed identity path', () => {
+    const args = buildSshConnectionArgs({ ...baseRemote, identityFile: '$HOME/.ssh/id_ed25519' });
+    expect(args.join(' ')).toContain(`-i '${HOME}/.ssh/id_ed25519'`);
+  });
+
+  it('empty options ⇒ exactly the historical token set (back-compat)', () => {
+    // Today: ssh -o BatchMode=yes (+ -p only when set). Nothing else.
+    expect(buildSshConnectionArgs(baseRemote)).toEqual(['ssh', '-o BatchMode=yes']);
+    expect(buildSshConnectionArgs({ ...baseRemote, port: 2200 })).toEqual(['ssh', '-o BatchMode=yes', '-p 2200']);
+  });
+});
+
+describe('COD-107 buildRemoteLaunchCommand — threads connection args', () => {
+  it('emits the aa-desktop ssh connection options ahead of -t and the target', () => {
+    const command = buildRemoteLaunchCommand({ mode: 'shell', remote: aaDesktop, sessionId: SESSION_ID });
+
+    expect(command).toContain('-p 2222');
+    expect(command).toContain(`-i '${HOME}/.ssh/remote_ed25519'`);
+    expect(command).toContain("-o 'ProxyCommand=nc -X 5 -x 127.0.0.1:1080 %h %p'");
+    expect(command).toContain("-o 'StrictHostKeyChecking=accept-new'");
+    expect(command).toContain('-t');
+    expect(command).toContain('aakht@192.168.55.170');
+    expect(command).toContain('tmux -L codeman new-session -A');
+
+    // Connection options come BEFORE -t / the target / the tmux command.
+    const idxProxy = command.indexOf('ProxyCommand=');
+    const idxTarget = command.indexOf('aakht@192.168.55.170');
+    expect(idxProxy).toBeLessThan(idxTarget);
+  });
+
+  it('back-compat: a remote with no advanced options is byte-identical to the historical form', () => {
+    const command = buildRemoteLaunchCommand({ mode: 'shell', remote: baseRemote, sessionId: SESSION_ID });
+    // Reconstruct the historical command using the SAME nested POSIX
+    // single-quote escaping the production code uses, to prove byte-identity.
+    const sh = (s: string) => "'" + s.replace(/'/g, "'\\''") + "'";
+    const remoteName = `codeman-${SESSION_ID.slice(0, 8)}`;
+    const path = sh('/home/ubuntu/work');
+    const paneCommand = `cd ${path} && exec bash -l`;
+    const tmuxInvocation = [
+      `tmux -L codeman new-session -A -s ${remoteName} -c ${path} ${sh(paneCommand)}`,
+      'set -g status off',
+      'set -g mouse off',
+      'set -sg escape-time 0',
+      'set -g prefix C-q',
+    ].join(' \\; ');
+    const expected = `ssh -o BatchMode=yes -t ${remoteSshTarget(baseRemote)} ${sh(tmuxInvocation)}`;
+    expect(command).toBe(expected);
+  });
+
+  it('back-compat: port-only remote matches the historical -p placement', () => {
+    const command = buildRemoteLaunchCommand({
+      mode: 'shell',
+      remote: { ...baseRemote, port: 2222 },
+      sessionId: SESSION_ID,
+    });
+    expect(command).toMatch(/^ssh -o BatchMode=yes -t -p 2222 ubuntu@10\.0\.0\.42 /);
+  });
+});
+
+describe('COD-107 buildRemoteTmuxCheckCommand — same connection options as the launch', () => {
+  it('uses the shared connection args (proxy/identity/port) plus ConnectTimeout', () => {
+    const cmd = buildRemoteTmuxCheckCommand(aaDesktop);
+    expect(cmd).toContain('-o BatchMode=yes');
+    expect(cmd).toContain('-o ConnectTimeout=10');
+    expect(cmd).toContain('-p 2222');
+    expect(cmd).toContain(`-i '${HOME}/.ssh/remote_ed25519'`);
+    expect(cmd).toContain("-o 'ProxyCommand=nc -X 5 -x 127.0.0.1:1080 %h %p'");
+    expect(cmd).toContain('aakht@192.168.55.170');
+    expect(cmd).toContain("'command -v tmux'");
+  });
+
+  it('back-compat: no advanced options ⇒ unchanged probe string', () => {
+    expect(buildRemoteTmuxCheckCommand({ username: 'ubuntu', host: '10.0.0.42' })).toBe(
+      "ssh -o BatchMode=yes -o ConnectTimeout=10 ubuntu@10.0.0.42 'command -v tmux'"
+    );
+    expect(buildRemoteTmuxCheckCommand({ username: 'ubuntu', host: '10.0.0.42', port: 2222 })).toContain('-p 2222');
+  });
+});

test/routes/case-routes.test.ts

@@ -237,6 +237,72 @@ describe('case-routes', () => {
       ]);
     });
 
+    // COD-107 — advanced SSH connection options (port, identity, SOCKS proxy,
+    // jump host, escape-hatch -o options) round-trip through the host schema.
+    it('persists advanced SSH options (port/identity/socks/jump/extra) on a remote host', async () => {
+      setupRemoteConfigStore();
+
+      const create = await harness.app.inject({
+        method: 'POST',
+        url: '/api/remote-hosts',
+        payload: {
+          id: 'aa-desktop',
+          label: 'aa-desktop',
+          host: '192.168.55.170',
+          username: 'aakht',
+          port: 2222,
+          identityFile: '~/.ssh/remote_ed25519',
+          socksProxy: '127.0.0.1:1080',
+          jumpHost: 'bastion@10.0.0.1:22',
+          extraSshOptions: ['StrictHostKeyChecking=accept-new'],
+        },
+      });
+      expect(create.statusCode).toBe(200);
+      expect(JSON.parse(create.body)).toMatchObject({ success: true });
+
+      const list = await harness.app.inject({ method: 'GET', url: '/api/remote-hosts' });
+      expect(JSON.parse(list.body).data).toEqual([
+        expect.objectContaining({
+          id: 'aa-desktop',
+          port: 2222,
+          identityFile: '~/.ssh/remote_ed25519',
+          socksProxy: '127.0.0.1:1080',
+          jumpHost: 'bastion@10.0.0.1:22',
+          extraSshOptions: ['StrictHostKeyChecking=accept-new'],
+        }),
+      ]);
+    });
+
+    it('rejects a malformed extraSshOptions entry (not KEY=VALUE) with INVALID_INPUT', async () => {
+      setupRemoteConfigStore();
+
+      const create = await harness.app.inject({
+        method: 'POST',
+        url: '/api/remote-hosts',
+        payload: {
+          id: 'bad-host',
+          label: 'bad',
+          host: '10.0.0.9',
+          username: 'ubuntu',
+          extraSshOptions: ['not a valid option'],
+        },
+      });
+      expect(create.statusCode).toBe(httpStatusForErrorCode(ApiErrorCode.INVALID_INPUT));
+      expect(JSON.parse(create.body)).toMatchObject({ success: false, errorCode: ApiErrorCode.INVALID_INPUT });
+    });
+
+    it('rejects a malformed socksProxy (missing port) with INVALID_INPUT', async () => {
+      setupRemoteConfigStore();
+
+      const create = await harness.app.inject({
+        method: 'POST',
+        url: '/api/remote-hosts',
+        payload: { id: 'bad2', label: 'bad2', host: '10.0.0.9', username: 'ubuntu', socksProxy: '127.0.0.1' },
+      });
+      expect(create.statusCode).toBe(httpStatusForErrorCode(ApiErrorCode.INVALID_INPUT));
+      expect(JSON.parse(create.body)).toMatchObject({ success: false });
+    });
+
     it('links a remote case and includes it in GET /api/cases', async () => {
       setupRemoteConfigStore();
       mockedReaddir.mockRejectedValue(new Error('ENOENT'));

test/tmux-manager.test.ts

@@ -98,7 +98,7 @@ describe('TmuxManager (unit)', () => {
   });
 
   describe('remote launch command builder', () => {
-    it('wraps codex command overrides in ssh with remote cd', () => {
+    it('wraps codex command overrides in ssh with remote tmux launch', () => {
       const command = buildRemoteLaunchCommand({
         mode: 'codex',
         remote: {
@@ -109,13 +109,14 @@ describe('TmuxManager (unit)', () => {
           remotePath: '/home/ubuntu/work',
           commands: { codex: 'exec codx personal' },
         },
+        sessionId: 'abc123def456',
       });
 
       expect(command).toContain('ssh');
       expect(command).toContain('BatchMode=yes');
       expect(command).toContain('ubuntu@10.0.0.42');
       expect(command).toContain('/home/ubuntu/work');
-      expect(command).toContain('bash -lc');
+      expect(command).toContain('tmux -L codeman new-session -A');
       expect(command).toContain('exec codx personal');
     });
 
@@ -129,6 +130,7 @@ describe('TmuxManager (unit)', () => {
           username: 'ubuntu',
           remotePath: '/home/ubuntu/work',
         },
+        sessionId: 'abc123def456',
       });
 
       expect(command).toContain('exec bash -l');