From f464a22bc3037308ee41c790ad9fd3070fdfc3d6 Mon Sep 17 00:00:00 2001
From: Codeman maintainer <noreply@anthropic.com>
Date: Fri, 6 Nov 2026 03:06:47 +0100
Subject: [PATCH] fix(adopt): bring the docker and ssh transports up to master

Docker discovery now spawns dockerEngineArgv(), not the shell-quoted
buildDockerBaseArgs(): execFile passed those quotes through, so docker
--context "'default'" failed and every container behind a named context or
remote daemon read as unreachable.

The ssh probe and attach gain withRemoteTmuxPath() like every other remote tmux
call, run in an explicit sh because the guard chain is POSIX and the remote
login shell may be fish, and the probe holds a slot of the remote-ssh limiter
and execs ssh so a timeout reaches it. Notes from a remote scan are no longer
dropped, and every note now opens with its location.

The adopted branch of killSession no longer blocks the event loop on docker or
tmux, kills the in-container view by exact name, and clears the pane-exit and
reconnect state the non-owned remote branch does. An adopted wrapper reports
no injected statusline, since nothing could carry it. Key tables on the foreign
server are left alone on purpose, and the invocation now says so.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/docker-hosts.ts           |   2 +-
 src/foreign-tmux-discovery.ts |  74 +++++++++++++-----
 src/foreign-tmux.ts           |  28 ++++++-
 src/tmux-manager.ts           |  25 +++---
 test/foreign-tmux.test.ts     | 143 +++++++++++++++++++++++++++++++++-
 5 files changed, 237 insertions(+), 35 deletions(-)

diff --git a/src/docker-hosts.ts b/src/docker-hosts.ts
index f2ce722d..45b8d17b 100644
--- a/src/docker-hosts.ts
+++ b/src/docker-hosts.ts
@@ -1014,7 +1014,7 @@ export function resolveDockerCredentialArtifacts(
  * string; argv arrays must NOT carry literal quotes (mirror of docker-export's
  * dockerArgv).
  */
-function dockerEngineArgv(docker: Pick<SessionDocker, 'engine' | 'context' | 'daemonHost'>): string[] {
+export function dockerEngineArgv(docker: Pick<SessionDocker, 'engine' | 'context' | 'daemonHost'>): string[] {
   const argv: string[] = [docker.engine === 'podman' ? 'podman' : 'docker'];
   if (docker.context) argv.push('--context', docker.context);
   if (docker.daemonHost) argv.push('-H', docker.daemonHost);
diff --git a/src/foreign-tmux-discovery.ts b/src/foreign-tmux-discovery.ts
index 6c5e46a2..4921c610 100644
--- a/src/foreign-tmux-discovery.ts
+++ b/src/foreign-tmux-discovery.ts
@@ -34,16 +34,16 @@ import { promisify } from 'node:util';
 import {
   buildForeignProbeScript,
   classifyForeignPaneMode,
+  foreignRemoteShellCommand,
   foreignSessionId,
   isAdoptableSessionName,
   isAdoptableSocketPath,
   isCodemanOwnedPane,
   parseForeignProbeOutput,
 } from './foreign-tmux.js';
-import { buildDockerBaseArgs, shellescape } from './docker-hosts.js';
-import { buildSshConnectionArgs, remoteSshTarget } from './remote-hosts.js';
-import { readDockerCases, readDockerHosts } from './docker-hosts.js';
-import { readRemoteHosts } from './remote-hosts.js';
+import { dockerEngineArgv, readDockerCases, readDockerHosts } from './docker-hosts.js';
+import { buildSshConnectionArgs, readRemoteHosts, remoteSshTarget, shellescape } from './remote-hosts.js';
+import { runWithRemoteSshLimit } from './remote-ssh-limiter.js';
 import { resolveTmuxSocketName, getDataDir } from './config/instance.js';
 import { FOREIGN_CACHE_TTL_MS, FOREIGN_PROBE_MAX_BYTES, FOREIGN_PROBE_TIMEOUT_MS } from './config/foreign-tmux.js';
 import type { ForeignDiscoveryResult, ForeignTmuxSession } from './types/foreign-tmux.js';
@@ -63,13 +63,18 @@ const PROBE_OPTS = {
 /**
  * Turn one probe's stdout into candidates. Shared by all three transports, so a
  * container's sessions and the host's are classified by identical rules.
+ *
+ * `where` opens every note this scan writes (`local`, `docker <name>`, `remote
+ * <label>`). The browser tells the two kinds apart by it: a local note is re-read on
+ * every poll, a container or host note only by the next explicit scan.
  */
 function candidatesFrom(
   stdout: string,
   location: ForeignTmuxSession['location'],
   hostKey: string,
   extra: Pick<ForeignTmuxSession, 'hostId' | 'hostLabel' | 'containerName'>,
-  notes?: string[]
+  where: string,
+  notes: string[]
 ): ForeignTmuxSession[] {
   const probe = parseForeignProbeOutput(stdout);
   const ownSocket = resolveTmuxSocketName();
@@ -112,9 +117,9 @@ function candidatesFrom(
       workingDir: pane.paneCurrentPath,
     });
   }
-  if (unsafe && notes) {
+  if (unsafe) {
     notes.push(
-      `${unsafe} session(s) skipped: the tmux session name or socket path contains characters Codeman will not pass to a shell`
+      `${where}: ${unsafe} session(s) skipped, the tmux session name or socket path contains characters Codeman will not pass to a shell`
     );
   }
   return out;
@@ -145,7 +150,7 @@ export async function discoverLocalForeign(force = false): Promise<ForeignDiscov
       // argv array: no outer shell, so the script's own `$TMUX_TMPDIR`/`$(id -u)`
       // reach the inner sh intact (see @fileoverview).
       const { stdout } = await execFileAsync('sh', ['-c', buildForeignProbeScript()], PROBE_OPTS);
-      sessions = candidatesFrom(stdout, 'local', 'local', {}, notes);
+      sessions = candidatesFrom(stdout, 'local', 'local', {}, 'local', notes);
     } catch {
       // No tmux, no sockets, or a probe that timed out. "Nothing to adopt here"
       // is the only honest answer and it is never an error to the caller.
@@ -171,7 +176,7 @@ export function invalidateForeignCache(): void {
 // ===========================================================================
 
 /** Connection facts for one adoptable container, resolved from the registries. */
-interface DockerTargetInfo {
+export interface DockerTargetInfo {
   hostId: string;
   label: string;
   containerName: string;
@@ -204,6 +209,18 @@ function dockerTargets(cases: DockerCase[], hosts: DockerHost[]): DockerTargetIn
   return out;
 }
 
+/**
+ * The argv of one in-container probe.
+ *
+ * ⚠️ `dockerEngineArgv`, never `buildDockerBaseArgs`, whose `--context` and `-H`
+ * values are shell-quoted for the launch string. `execFile` passes those quotes
+ * through literally, so `docker --context "'default'"` answered "context not found"
+ * and every container behind a named context or a remote daemon read as unreachable.
+ */
+export function foreignDockerProbeArgv(target: DockerTargetInfo): string[] {
+  return [...dockerEngineArgv(target.base), 'exec', target.containerName, 'sh', '-lc', buildForeignProbeScript()];
+}
+
 /**
  * Scan the containers behind the caller's docker cases. On demand only.
  *
@@ -222,19 +239,16 @@ export async function discoverDockerForeign(cases: DockerCase[]): Promise<Foreig
 
   await Promise.all(
     targets.map(async (t) => {
-      const [engine, ...baseFlags] = buildDockerBaseArgs(t.base);
+      const [engine, ...args] = foreignDockerProbeArgv(t);
       try {
-        const { stdout } = await execFileAsync(
-          engine,
-          [...baseFlags, 'exec', t.containerName, 'sh', '-lc', buildForeignProbeScript()],
-          PROBE_OPTS
-        );
+        const { stdout } = await execFileAsync(engine, args, PROBE_OPTS);
         sessions.push(
           ...candidatesFrom(
             stdout,
             'docker',
             `${t.hostId} ${t.containerName}`,
             { hostId: t.hostId, hostLabel: t.label, containerName: t.containerName },
+            `docker ${t.containerName}`,
             notes
           )
         );
@@ -251,6 +265,20 @@ export async function discoverDockerForeign(cases: DockerCase[]): Promise<Foreig
 // Remote
 // ===========================================================================
 
+/**
+ * The ssh command line of one remote probe.
+ *
+ * `exec` so a timeout kill reaches ssh itself, not only the local `sh -c` around it.
+ */
+export function foreignRemoteProbeCommand(host: RemoteHost): string {
+  return [
+    'exec',
+    ...buildSshConnectionArgs(host),
+    remoteSshTarget(host),
+    shellescape(foreignRemoteShellCommand(buildForeignProbeScript())),
+  ].join(' ');
+}
+
 /**
  * Scan saved ssh hosts. On demand only — this is the expensive one.
  *
@@ -258,6 +286,10 @@ export async function discoverDockerForeign(cases: DockerCase[]): Promise<Foreig
  * probe crosses one extra shell and must be single-quoted. `shellescape` does
  * that, and `buildForeignProbeScript()` is single-quote-free precisely so the
  * escaping stays a wrap rather than a rewrite.
+ *
+ * Each host holds a slot of the shared remote-ssh limiter: one saved host per
+ * connection, all at once, is the burst OpenSSH's `MaxStartups` starts dropping.
+ * A host that waits too long for a slot reads as unreachable this round.
  */
 export async function discoverRemoteForeign(hosts: RemoteHost[]): Promise<ForeignDiscoveryResult> {
   if (IS_TEST_MODE) return { sessions: [], scannedAt: Date.now(), notes: [] };
@@ -267,14 +299,14 @@ export async function discoverRemoteForeign(hosts: RemoteHost[]): Promise<Foreig
 
   await Promise.all(
     hosts.map(async (host) => {
-      const cmd = [...buildSshConnectionArgs(host), remoteSshTarget(host), shellescape(buildForeignProbeScript())].join(
-        ' '
-      );
+      const where = `remote ${host.label}`;
       try {
-        const { stdout } = await execAsync(cmd, PROBE_OPTS);
-        sessions.push(...candidatesFrom(stdout, 'remote', host.id, { hostId: host.id, hostLabel: host.label }));
+        const { stdout } = await runWithRemoteSshLimit(() => execAsync(foreignRemoteProbeCommand(host), PROBE_OPTS), {
+          maxWaitMs: FOREIGN_PROBE_TIMEOUT_MS,
+        });
+        sessions.push(...candidatesFrom(stdout, 'remote', host.id, { hostId: host.id, hostLabel: host.label }, where, notes));
       } catch {
-        notes.push(`remote ${host.label}: unreachable, or no tmux`);
+        notes.push(`${where}: unreachable, or no tmux`);
       }
     })
   );
diff --git a/src/foreign-tmux.ts b/src/foreign-tmux.ts
index 0299195b..a8311ce1 100644
--- a/src/foreign-tmux.ts
+++ b/src/foreign-tmux.ts
@@ -70,6 +70,7 @@
 
 import { collectDescendants } from './proc-tree.js';
 import { listClis } from './config/cli-registry/registry.js';
+import { withRemoteTmuxPath } from './remote-hosts.js';
 import { FOREIGN_MAX_PANES, FOREIGN_MAX_PROCS, FOREIGN_MAX_SOCKETS } from './config/foreign-tmux.js';
 import type { ForeignPaneProbe, ForeignTmuxLocationKind } from './types/foreign-tmux.js';
 import type { SessionAdopt, SessionMode } from './types/session.js';
@@ -597,7 +598,7 @@ export interface ForeignAttachTarget {
  *   noise out of the pane — the message we print says it better.
  * - ⚠️ The `=` prefix cannot go on `new-session -t` itself: tmux reads it as part of
  *   the name and creates a group literally called `=work`. It has to be a separate
- *   `has-session`. The read-only `attach-session` fallback takes `=` too.
+ *   `has-session`.
  * - `new-session -t` creates a session in the target's GROUP: same windows, our
  *   own session options and current window (NOT our own size — see @fileoverview
  *   for the measurement that disproved that).
@@ -620,6 +621,12 @@ export interface ForeignAttachTarget {
  *   killing a session in a group removes only that session (measured: the owner's
  *   `work` survived its grouped view being killed). `2>/dev/null` because "no such
  *   session" is the normal case, not an error.
+ * - ⚠️ Nothing here touches the prefix table, unlike the nested servers Codeman runs
+ *   itself (`nestedPrefixTableResetCommands`). Our own socket already has its table
+ *   reduced by `createSession`, but key tables are SERVER-WIDE, so reducing the foreign
+ *   one would rewrite the owner's keys for every session on their server, and it would
+ *   outlive our detach. Same reason `window-size` is left alone above. The owner's
+ *   bindings stay reachable from a tab, behind our own `send-prefix`, as theirs to use.
  * - Single line: the string crosses `bash -c "..."`, where a real newline would
  *   not survive JSON escaping.
  */
@@ -703,10 +710,25 @@ export function buildForeignDockerViewKillCommand(opts: {
 }): string {
   return (
     `${opts.dockerBase} exec ${fshq(opts.containerName)} ` +
-    `tmux -S ${fshq(opts.socketPath)} kill-session -t ${fshq(opts.viewSession)}`
+    `tmux -S ${fshq(opts.socketPath)} kill-session -t ${fshq(`=${opts.viewSession}`)}`
   );
 }
 
+/**
+ * A POSIX script as the command line of an ssh connection.
+ *
+ * ssh hands its command to the remote user's LOGIN shell, which may be fish: the
+ * guard chain's `{ ...; }` and the probe's `${VAR:-x}` are POSIX, so they run in an
+ * explicit `sh`. The PATH line stays outside it because it is the part written for
+ * whatever that shell is (`withRemoteTmuxPath`), and sshd's non-interactive PATH can
+ * miss a Homebrew or per-user tmux, the same reason every other remote tmux call has
+ * it. Single-quote-free input stays single-quote-free here, and `exec` keeps the
+ * process tree one level shorter.
+ */
+export function foreignRemoteShellCommand(script: string): string {
+  return withRemoteTmuxPath(`exec sh -c ${fshq(script)}`);
+}
+
 export interface ForeignRemoteAttachOptions extends ForeignAttachTarget {
   /** `buildSshConnectionArgs(host)` — `['ssh', '-o BatchMode=yes', ...]`. */
   sshArgs: string[];
@@ -724,7 +746,7 @@ export interface ForeignRemoteAttachOptions extends ForeignAttachTarget {
  */
 export function buildForeignRemoteAttachCommand(opts: ForeignRemoteAttachOptions): string {
   const [ssh, batchMode, ...rest] = opts.sshArgs;
-  return [ssh, batchMode, '-t', ...rest, opts.sshTarget, fshq(buildForeignTmuxInvocation(opts))]
+  return [ssh, batchMode, '-t', ...rest, opts.sshTarget, fshq(foreignRemoteShellCommand(buildForeignTmuxInvocation(opts)))]
     .filter(Boolean)
     .join(' ');
 }
diff --git a/src/tmux-manager.ts b/src/tmux-manager.ts
index 40dceb93..bb4e345d 100644
--- a/src/tmux-manager.ts
+++ b/src/tmux-manager.ts
@@ -1917,7 +1917,7 @@ function buildRemoteSessionCommand(options: {
  * `kill-session`. It is the same reasoning that keeps a non-owned REMOTE session
  * safe (see the detach-not-kill early return in `killSession`).
  */
-function buildAdoptSessionCommand(adopt: SessionAdopt, sessionId: string): string {
+export function buildAdoptSessionCommand(adopt: SessionAdopt, sessionId: string): string {
   const target = {
     socketPath: adopt.socketPath,
     targetSession: adopt.targetSession,
@@ -2614,7 +2614,8 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     const { command: statusLineCommand, state: statusLine } = await this._resolveStatusLine(
       mode,
       workingDir,
-      !!(remote || docker)
+      // An adopted wrapper launches no agent, so nothing can carry the exporter.
+      !!(remote || docker || adopt)
     );
     const idleCompactionOff = await this._resolveIdleCompactionOptOut(mode, statusLine, keepWarm, spawnedByAgent);
     // The user's own REAL statusLine, if any (walked via Claude Code's own
@@ -2937,7 +2938,8 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     const { command: statusLineCommand, state: statusLine } = await this._resolveStatusLine(
       mode,
       workingDir,
-      !!(remote || docker)
+      // An adopted wrapper launches no agent, so nothing can carry the exporter.
+      !!(remote || docker || adopt)
     );
     const idleCompactionOff = await this._resolveIdleCompactionOptOut(mode, statusLine, keepWarm, spawnedByAgent);
     const userStatusLineCommand = statusLineCommand ? await findEffectiveUserStatusLineCommand(workingDir) : undefined;
@@ -3218,24 +3220,27 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       // A `docker exec` survives its client, so the in-container view would stay
       // attached forever and leak. Best-effort, and it can only reach OUR view.
       // See buildForeignDockerViewKillCommand for why local/remote need nothing.
+      // Fire and forget like the owned docker branch below: a daemon that stopped
+      // answering must not hold the event loop for the whole timeout.
       if (session.adopt.location === 'docker' && session.adopt.docker) {
         try {
-          execSync(
-            `${buildForeignDockerViewKillCommand({
+          exec(
+            buildForeignDockerViewKillCommand({
               dockerBase: buildDockerBaseArgs(session.adopt.docker).join(' '),
               containerName: session.adopt.docker.containerName,
               socketPath: session.adopt.socketPath,
               viewSession: session.adopt.viewSession || foreignViewSessionName(sessionId),
-            })} 2>/dev/null`,
-            { timeout: EXEC_TIMEOUT_MS, stdio: 'ignore' }
+            }),
+            { timeout: EXEC_TIMEOUT_MS },
+            () => {}
           );
         } catch {
-          // The container may be gone, or the view already collected.
+          // Best-effort: the container may be gone, or the view already collected.
         }
       }
       if (isValidMuxName(session.muxName)) {
         try {
-          execSync(`${this.tmux()} kill-session -t "${session.muxName}" 2>/dev/null`, {
+          await execAsync(`${this.tmux()} kill-session -t "${session.muxName}" 2>/dev/null`, {
             timeout: EXEC_TIMEOUT_MS,
           });
         } catch {
@@ -3243,7 +3248,9 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
         }
       }
       this.lastPaneCount.delete(session.muxName);
+      this.clearPaneExit(session.muxName);
       this.sessions.delete(sessionId);
+      this.clearRemoteReconnectState(sessionId);
       this.saveSessions();
       this.emit('sessionKilled', { sessionId });
       return true;
diff --git a/test/foreign-tmux.test.ts b/test/foreign-tmux.test.ts
index 78470650..e80434b6 100644
--- a/test/foreign-tmux.test.ts
+++ b/test/foreign-tmux.test.ts
@@ -6,7 +6,11 @@
  * would quietly undo. Each one has a comment naming what actually went wrong.
  */
 
-import { describe, it, expect, vi } from 'vitest';
+import { execSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, it, expect, vi } from 'vitest';
 import {
   buildForeignProbeScript,
   parseForeignProbeOutput,
@@ -19,9 +23,13 @@ import {
   buildForeignAttachCommand,
   buildForeignDockerAttachCommand,
   buildForeignRemoteAttachCommand,
+  buildForeignDockerViewKillCommand,
   buildForeignTmuxInvocation,
   foreignCliSignatures,
 } from '../src/foreign-tmux.js';
+import { foreignDockerProbeArgv, foreignRemoteProbeCommand } from '../src/foreign-tmux-discovery.js';
+import { buildAdoptSessionCommand } from '../src/tmux-manager.js';
+import type { RemoteHost, SessionAdopt } from '../src/types/session.js';
 import { PROC_WALK_MAX_NODES } from '../src/proc-tree.js';
 import { STOCK_CLIS } from '../src/config/cli-registry/stock.js';
 import { hooksAvailableForMode, sessionHookOptions } from '../src/web/session-wait-registry.js';
@@ -390,6 +398,139 @@ describe('attach command builders', () => {
   });
 });
 
+describe('the docker and ssh transports', () => {
+  const host: RemoteHost = {
+    id: 'h1',
+    label: 'Build box',
+    host: 'build.example',
+    username: 'me',
+  } as RemoteHost;
+  const dockerTarget = {
+    hostId: 'd1',
+    label: 'ci',
+    containerName: 'box',
+    base: { engine: 'docker' as const, context: 'my ctx', daemonHost: 'tcp://10.0.0.1:2375' },
+  };
+
+  it('hands execFile a docker argv with no shell quoting in it', () => {
+    // `docker --context "'my ctx'"` is what the shell-quoted builder gave execFile:
+    // "context not found", so every container behind a context read as unreachable.
+    const argv = foreignDockerProbeArgv(dockerTarget);
+    expect(argv.slice(0, 5)).toEqual(['docker', '--context', 'my ctx', '-H', 'tcp://10.0.0.1:2375']);
+    expect(argv.slice(5, 9)).toEqual(['exec', 'box', 'sh', '-lc']);
+    for (const token of argv) expect(token).not.toContain("'");
+  });
+
+  it('runs the ssh probe in sh with the remote tmux PATH, so a timeout reaches ssh', () => {
+    const cmd = foreignRemoteProbeCommand(host);
+    expect(cmd.startsWith('exec ssh ')).toBe(true);
+    expect(cmd).toContain('me@build.example');
+    expect(cmd).toContain('/opt/homebrew/bin');
+    expect(cmd).toContain('exec sh -c');
+    expect(cmd).toContain('list-panes');
+  });
+
+  it('puts the same PATH and sh on the ssh attach', () => {
+    const cmd = buildForeignRemoteAttachCommand({
+      socketPath: '/tmp/tmux-1000/default',
+      targetSession: 'work',
+      viewSession: 'codeman-view-abc12345',
+      sshArgs: ['ssh', '-o BatchMode=yes'],
+      sshTarget: 'me@host',
+    });
+    expect(cmd).toContain('/opt/homebrew/bin');
+    expect(cmd).toContain('exec sh -c');
+  });
+
+  it('kills the in-container view by exact name', () => {
+    // Without `=` tmux prefix-matches, and the view is grouped with the owner's work.
+    expect(
+      buildForeignDockerViewKillCommand({
+        dockerBase: 'docker',
+        containerName: 'box',
+        socketPath: '/tmp/tmux-0/default',
+        viewSession: 'codeman-view-abc12345',
+      })
+    ).toContain("kill-session -t '=codeman-view-abc12345'");
+  });
+
+  describe('buildAdoptSessionCommand', () => {
+    const adopt: SessionAdopt = {
+      location: 'local',
+      socketPath: '/tmp/tmux-1000/default',
+      targetSession: 'work',
+      viewSession: '',
+    };
+
+    it('attaches in place for a local target, and names the view after our session', () => {
+      const cmd = buildAdoptSessionCommand(adopt, 'abc12345-rest');
+      expect(cmd).toContain("has-session -t '=work'");
+      expect(cmd).toContain("-s 'codeman-view-abc12345'");
+      expect(cmd).not.toMatch(/\b(ssh|docker)\b/);
+    });
+
+    it('goes through the saved engine for a container, shell-quoted for the launch string', () => {
+      const cmd = buildAdoptSessionCommand(
+        {
+          ...adopt,
+          location: 'docker',
+          docker: { hostId: 'd1', label: 'ci', engine: 'podman', containerName: 'box', context: 'my ctx' },
+        },
+        'abc12345'
+      );
+      expect(cmd).toContain("podman --context 'my ctx' exec -it 'box' sh -lc");
+    });
+
+    it('goes through the saved connection for an ssh host', () => {
+      const cmd = buildAdoptSessionCommand(
+        { ...adopt, location: 'remote', remote: { hostId: 'h1', label: 'b', host: 'h.example', username: 'me', port: 2222 } },
+        'abc12345'
+      );
+      expect(cmd.startsWith('ssh -o BatchMode=yes -t ')).toBe(true);
+      expect(cmd).toContain('me@h.example');
+      expect(cmd).toContain('2222');
+    });
+  });
+
+  describe('the ssh attach survives every shell on its way', () => {
+    // bash -c "<JSON>" at respawn-pane, the single quotes around the remote command,
+    // the remote login shell, then sh -c. Stand-ins for ssh and tmux at the two ends
+    // show what a real tmux would receive, which no substring check can.
+    let home: string;
+    let bin: string;
+
+    beforeEach(() => {
+      home = mkdtempSync(join(tmpdir(), 'foreign-ssh-'));
+      // $HOME/bin, because the remote PATH line puts it ahead of a real tmux.
+      bin = join(home, 'bin');
+      mkdirSync(bin);
+      // The real thing hands its LAST argument to the remote login shell.
+      writeFileSync(join(bin, 'ssh'), '#!/bin/sh\nfor last; do :; done\nexec sh -c "$last"\n', { mode: 0o755 });
+      writeFileSync(join(bin, 'tmux'), '#!/bin/sh\nfor a; do printf "<%s>" "$a"; done\nprintf "\\n"\n', { mode: 0o755 });
+    });
+
+    afterEach(() => {
+      rmSync(home, { recursive: true, force: true });
+    });
+
+    it('delivers a spaced name as one argument to each tmux command', () => {
+      const launch = buildForeignRemoteAttachCommand({
+        socketPath: '/tmp/tmux-1000/my sock',
+        targetSession: 'my work',
+        viewSession: 'codeman-view-abc12345',
+        sshArgs: ['ssh', '-o BatchMode=yes'],
+        sshTarget: 'me@host',
+      });
+      const out = execSync(`bash -c ${JSON.stringify(launch)}`, {
+        encoding: 'utf-8',
+        env: { ...process.env, HOME: home, PATH: `${bin}:${process.env.PATH}` },
+      });
+      expect(out).toContain('<-S></tmp/tmux-1000/my sock><has-session><-t><=my work>');
+      expect(out).toContain('<new-session><-t><my work><-s><codeman-view-abc12345><;><set-option>');
+    });
+  });
+});
+
 describe('foreignCliSignatures', () => {
   it('covers every stock CLI that declares a binary — including the one the hand-written table missed', () => {
     // The table this replaced listed eight CLI ids by hand and had already gone