@starci/hfs 4.4.1 → 4.5.1

package/stack/docker-transport.mjs

@@ -1,15 +1,19 @@
 // docker-transport.mjs - lets the verbs that drive the docker CLI (deploy, converge, verify, rollback, prune) reach the manager from an OPERATOR
-// machine. In CI `connect` writes the ssh config and DOCKER_HOST; on an operator machine the key lives in the sealed members, so the docker CLI
-// is run with a private HOME that holds an ssh config for the sealed session and DOCKER_HOST=ssh://<alias>. Only `docker` children that did not get
+// machine or CI. The command shares one POSIX control master (including remote scripts) or one Windows Docker socket tunnel. On an operator
+// machine the key lives in the sealed members, so the docker CLI is run with a private HOME that holds the session's ssh config. Only children that did not get
 // an explicit environment are affected (the minimal environment of `docker stack config` stays exactly as the render built it). The key lives in
 // a private temp directory that is overwritten and removed when the verb ends; it is never in argv, a line or an error.
 import fs from 'node:fs';
 import path from 'node:path';
 import { writePrivate } from './private-file.mjs';
 import { openSealedSession } from './remote.mjs';
+import { controlSettings, createSshSession, sessionDirectory } from './ssh-session.mjs';
+import { failure } from './errors.mjs';
 
 const ALIAS = 'stack-vps';
 const forward = (file) => file.replaceAll('\\', '/');
+const configPath = (file) => '"' + forward(file).replaceAll('"', '\\"') + '"';
+const controlLines = (controlPath) => controlSettings(configPath(controlPath)).map((setting) => `  ${setting.replace('=', ' ')}`);
 
 /** True when the operator's docker CLI has to be pointed at the manager by this module. */
 function needed(ctx, config, sshCmd) {
@@ -19,35 +23,109 @@ function needed(ctx, config, sshCmd) {
   return [sealed.ops, sealed.sshKey, sealed.knownHosts].every((slug) => fs.existsSync(path.join(config.secretsDir, `${slug}.enc`)));
 }
 
-function sshConfig(session) {
+function sshConfig(session, controlPath, windows) {
   const at = session.account.lastIndexOf('@');
   return [
     `Host ${ALIAS}`, `  HostName ${session.account.slice(at + 1)}`, `  User ${session.account.slice(0, at)}`,
-    `  IdentityFile ${forward(session.keyFile)}`, '  IdentitiesOnly yes', `  UserKnownHostsFile ${forward(session.knownFile)}`,
-    `  StrictHostKeyChecking ${session.strict}`, '  BatchMode yes', '  ConnectTimeout 20', '',
+    `  IdentityFile ${configPath(session.keyFile)}`, '  IdentitiesOnly yes', `  UserKnownHostsFile ${configPath(session.knownFile)}`,
+    `  StrictHostKeyChecking ${session.strict}`, '  BatchMode yes', '  ConnectTimeout 20',
+    ...(windows ? [] : controlLines(controlPath)), '',
   ].join('\n');
 }
 
 /** The environment of a docker child: a private HOME with the ssh config, DOCKER_HOST, and the operator's docker config (registry logins) kept. */
-function dockerEnvironment(ctx, session) {
+function dockerEnvironment(ctx, session, controlPath) {
   const home = path.join(session.dir, 'home');
-  fs.mkdirSync(path.join(home, '.ssh'), { recursive: true });
-  writePrivate(ctx, path.join(home, '.ssh', 'config'), sshConfig(session));
+  fs.mkdirSync(home, { recursive: true, mode: 0o700 });
+  fs.chmodSync(home, 0o700);
+  fs.mkdirSync(path.join(home, '.ssh'), { recursive: true, mode: 0o700 });
+  writePrivate(ctx, path.join(home, '.ssh', 'config'), sshConfig(session, controlPath, (ctx.platform ?? process.platform) === 'win32'));
   const operatorHome = ctx.env.HOME ?? ctx.env.USERPROFILE ?? '';
   const dockerConfig = ctx.env.DOCKER_CONFIG ?? (operatorHome ? path.join(operatorHome, '.docker') : undefined);
   return { ...ctx.env, HOME: home, USERPROFILE: home, DOCKER_HOST: `ssh://${ALIAS}`, ...(dockerConfig ? { DOCKER_CONFIG: dockerConfig } : {}) };
 }
 
+/** OpenSSH resolves its default config from the account database, so Docker needs a private PATH entry that supplies -F explicitly. */
+function privateSshEnvironment(ctx, env, dir, controlPath) {
+  if ((ctx.platform ?? process.platform) === 'win32') {
+    const home = path.join(dir, 'home');
+    fs.mkdirSync(home, { recursive: true, mode: 0o700 });
+    fs.chmodSync(home, 0o700);
+    const originalHome = env.HOME ?? env.USERPROFILE;
+    const dockerConfig = env.DOCKER_CONFIG ?? (originalHome ? path.join(originalHome, '.docker') : undefined);
+    return { env: { ...env, HOME: home, USERPROFILE: home, ...(dockerConfig ? { DOCKER_CONFIG: dockerConfig } : {}) }, executable: 'ssh' };
+  }
+  const originalHome = ctx.env.HOME;
+  const home = path.join(dir, 'home');
+  const config = path.join(home, '.ssh', 'config');
+  fs.mkdirSync(path.dirname(config), { recursive: true, mode: 0o700 });
+  if (!fs.existsSync(config)) {
+    const include = originalHome ? `Include ${configPath(path.join(originalHome, '.ssh', 'config'))}\n` : '';
+    writePrivate(ctx, config, ['Host *', ...controlLines(controlPath), 'Host *', include].join('\n'));
+  }
+  const executable = ctx.sshPath ?? findSsh(ctx.env.PATH);
+  const bin = path.join(home, 'bin');
+  fs.mkdirSync(bin, { mode: 0o700 });
+  const shim = path.join(bin, 'ssh');
+  writePrivate(ctx, shim, `#!/bin/sh\nexec ${posixQuote(executable)} -F ${posixQuote(config)} "$@"\n`);
+  fs.chmodSync(shim, 0o700);
+  const dockerConfig = env.DOCKER_CONFIG ?? (originalHome ? path.join(originalHome, '.docker') : undefined);
+  return { env: { ...env, HOME: home, PATH: `${bin}:${env.PATH ?? ctx.env.PATH ?? ''}`, ...(dockerConfig ? { DOCKER_CONFIG: dockerConfig } : {}) }, executable };
+}
+
+const posixQuote = (value) => "'" + value.replaceAll("'", "'\\''") + "'";
+
+function findSsh(searchPath = '') {
+  const executable = searchPath.split(':').map((dir) => path.join(dir, 'ssh')).find((file) => fs.existsSync(file));
+  if (!executable) throw failure('STACK_SSH_SESSION', 'cannot locate the SSH executable');
+  return path.resolve(executable);
+}
+
 /** Runs `body(ctx')` where ctx'.spawn points the docker CLI at the manager when this is an operator machine; otherwise `body(ctx)`. */
 export async function withDockerTransport(ctx, config, { sshCmd = null } = {}, body) {
-  if (!needed(ctx, config, sshCmd)) return body(ctx);
-  const session = openSealedSession(ctx, config);
-  const env = dockerEnvironment(ctx, session);
-  const spawn = (command, args, options = {}) => (command === 'docker' && options.env === undefined ? ctx.spawn(command, args, { ...options, env }) : ctx.spawn(command, args, options));
-  for (const note of session.notes) ctx.stderr(`${note}\n`);
+  if (sshCmd) return body(ctx);
+  const sealed = needed(ctx, config, sshCmd);
+  const alias = sealed ? ALIAS : sshAlias(ctx.env.DOCKER_HOST);
+  if (!alias) return body(ctx);
+  const session = sealed ? openSealedSession(ctx, config) : null;
+  const dir = session?.dir ?? sessionDirectory();
+  let connection;
+  let cleaned = false;
+  function cleanup() {
+    if (cleaned) return;
+    cleaned = true;
+    if (session) session.cleanup();
+    else fs.rmSync(dir, { recursive: true, force: true });
+  }
   try {
-    return await body(Object.create(ctx, { spawn: { value: spawn } }));
+    const controlPath = forward(path.join(dir, 'home', 'cm'));
+    const baseEnv = session ? dockerEnvironment(ctx, session, controlPath) : ctx.env;
+    const { env, executable } = privateSshEnvironment(ctx, baseEnv, dir, controlPath);
+    const configFile = path.join(env.HOME ?? '', '.ssh', 'config');
+    const options = ['-o', 'BatchMode=yes', '-o', 'ConnectTimeout=20'];
+    const argv = session || executable !== 'ssh' ? [executable, ...options, '-F', configFile, '--', alias] : ['ssh', ...options, '--', alias];
+    connection = createSshSession(ctx, { argv, env, controlPath, cleanup });
+    const spawn = dockerSpawn(ctx, connection, env, alias);
+    for (const note of session?.notes ?? []) ctx.stderr(`${note}\n`);
+    return await body(Object.create(ctx, { spawn: { value: spawn }, stackSsh: { value: connection } }));
   } finally {
-    session.cleanup();
+    try { await connection?.close(); } finally {
+      cleanup();
+    }
   }
 }
+
+/** Only SSH Docker endpoints belong to this connection; TCP, unix and explicitly supplied child environments keep their behavior. */
+function sshAlias(host) {
+  if (!host?.startsWith('ssh://')) return null;
+  const endpoint = new URL(host);
+  if (endpoint.port || endpoint.pathname && endpoint.pathname !== '/') return null;
+  return endpoint.username ? `${decodeURIComponent(endpoint.username)}@${endpoint.hostname}` : endpoint.hostname;
+}
+
+function dockerSpawn(ctx, connection, env, alias) {
+  return (command, args, options = {}) => {
+    if (command !== 'docker' || options.env !== undefined) return ctx.spawn(command, args, options);
+    return ctx.spawn(command, args, { ...options, env: { ...env, DOCKER_HOST: connection.dockerHost(alias) } });
+  };
+}

package/stack/release-store.mjs

@@ -5,7 +5,6 @@
 // the remote shell. The record holds names and digests, never a secret value. Files travel as text on stdin / stdout.
 import fs from 'node:fs';
 import path from 'node:path';
-import { eachInOrder, mapInOrder } from '../runtime/scripts/lib/in-order.mjs';
 import { firstLine, lines as splitLines } from './context.mjs';
 import { isReleaseId } from './digest.mjs';
 import { failure, refusal } from './errors.mjs';
@@ -56,9 +55,8 @@ export function createReleaseStore(config, ssh) {
     async store(dir, id) {
       const target = dirOf(id);
       const contents = FILES.map((name) => [name, readLocal(dir, name)]);
-      await run(`set -e; d="${target}"; if [ -d "$d" ]; then chmod -R u+w "$d"; else mkdir -p "$d"; fi`);
-      await eachInOrder(contents, ([name, text]) => run(`set -e; d="${target}"; cat > "$d/${name}"`, text));
-      await run(`set -e; d="${target}"; chmod 440 "$d/stack.yaml" "$d/release.json"; chmod 550 "$d"`);
+      const input = contents.map(([, text]) => Buffer.from(text, 'utf8').toString('base64')).join('\n') + '\n';
+      await run(`set -e; d="${target}"; if [ -d "$d" ]; then chmod -R u+w "$d"; else mkdir -p "$d"; fi; IFS= read -r stack; IFS= read -r release; printf '%s' "$stack" | base64 -d > "$d/stack.yaml"; printf '%s' "$release" | base64 -d > "$d/release.json"; chmod 440 "$d/stack.yaml" "$d/release.json"; chmod 550 "$d"`, input);
     },
     /** The release was verified: previous := current, current := id. */
     async accept(id) {
@@ -72,15 +70,22 @@ export function createReleaseStore(config, ssh) {
     /** Downloads a stored release (both files) into `targetDir` for a rollback or an audit. */
     async fetch(id, targetDir) {
       const source = dirOf(id);
-      const files = await mapInOrder(FILES, async (name) => [name, await run(`cat "${source}/${name}"`)]);
+      const out = await run(`set -e; for f in stack.yaml release.json; do test -r "${source}/$f"; base64 < "${source}/$f" | tr -d '\\n'; printf '\\n'; done`);
+      const frames = out.split('\n');
+      if (frames.length !== 3 || frames[2] !== '' || frames.slice(0, 2).some((frame) => !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(frame))) throw failure('STACK_RELEASE_SSH', 'invalid release response framing');
+      const files = FILES.map((name, index) => [name, Buffer.from(frames[index], 'base64').toString('utf8')]);
       fs.mkdirSync(targetDir, { recursive: true });
       for (const [name, text] of files) fs.writeFileSync(path.join(targetDir, name), text);
       return targetDir;
     },
     /** The stored releases, newest first: [{ id, current, previous }]. */
     async list() {
-      const [now, before] = [await pointer('current'), await pointer('previous')];
-      const out = await run(`cd "${base}/releases" 2>/dev/null && ls -1t || true`);
+      const pointerScript = (name) => `if [ -L "${base}/${name}" ]; then basename "$(readlink "${base}/${name}")"; else printf '\\n'; fi`;
+      const response = await run(`${pointerScript('current')}; ${pointerScript('previous')}; cd "${base}/releases" 2>/dev/null && ls -1t || true`);
+      const [current, previous, ...entries] = response.split('\n');
+      const now = isReleaseId(current) ? current : '';
+      const before = isReleaseId(previous) ? previous : '';
+      const out = entries.join('\n');
       return splitLines(out).filter(isReleaseId).map((id) => ({ id, current: id === now, previous: id === before }));
     },
   };

package/stack/remote.mjs

@@ -13,6 +13,7 @@ import path from 'node:path';
 import { tool } from './context.mjs';
 import { restrictToUser, writePrivate } from './private-file.mjs';
 import { refusal } from './errors.mjs';
+import { createSshSession, sessionDirectory } from './ssh-session.mjs';
 
 const ACCOUNT = /^[A-Za-z0-9._@-]+$/u;
 const CI_VARIABLES = ['VPS_SSH_KEY', 'VPS_KNOWN_HOSTS', 'VPS_HOST', 'VPS_USER'];
@@ -33,11 +34,11 @@ export const remoteDocker = (run, args) => run(['docker', ...args.map(shellQuote
 
 const noop = () => {};
 
-function makeRunner(ctx, argv, { cleanup = noop, notes = [] } = {}) {
+function makeRunner(ctx, argv, { cleanup = noop, notes = [], connection } = {}) {
   const [command, ...head] = argv;
   const run = (remote, { input } = {}) => {
     const options = input === undefined ? {} : { input: lfOnly(input) };
-    const result = tool(ctx, command, [...head, lfOnly(remote)], options);
+    const result = connection ? connection.remote(lfOnly(remote), options) : tool(ctx, command, [...head, lfOnly(remote)], options);
     if (result.error) return { status: 127, stdout: '', stderr: `cannot run ${command}: ${result.error.message}` };
     return { status: result.status ?? 1, stdout: result.stdout, stderr: result.stderr };
   };
@@ -119,14 +120,21 @@ export function openSealedSession(ctx, config) {
 function sealedRunner(ctx, config) {
   const session = openSealedSession(ctx, config);
   const argv = ['ssh', '-T', '-i', session.keyFile, '-o', 'IdentitiesOnly=yes', '-o', `UserKnownHostsFile=${session.knownFile}`, '-o', `StrictHostKeyChecking=${session.strict}`, '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=20', session.account];
-  return makeRunner(ctx, argv, { cleanup: session.cleanup, notes: session.notes });
+  return sessionRunner(ctx, argv, session.dir, session.cleanup, session.notes);
+}
+
+function sessionRunner(ctx, argv, dir, cleanup, notes = []) {
+  const connection = createSshSession(ctx, { argv, controlPath: path.join(dir, 'cm').replaceAll('\\', '/'), cleanup });
+  return makeRunner(ctx, argv, { connection, cleanup: connection.close, notes });
 }
 
 /** The ssh runner of one invocation (see the top of the file). */
 function sshRunner(ctx, config, { sshCmd = null } = {}) {
+  if (ctx.stackSsh && !sshCmd) return makeRunner(ctx, ['ssh'], { connection: ctx.stackSsh });
   if (sshCmd) return makeRunner(ctx, sshCommandArgv(sshCmd));
   if (config.remote.sealed && ctx.env.STARCI_STACK_SEALED_SSH === '1') return sealedRunner(ctx, config);
-  return makeRunner(ctx, ['ssh', ...SSH_OPTIONS, config.remote.host]);
+  const dir = sessionDirectory();
+  return sessionRunner(ctx, ['ssh', ...SSH_OPTIONS, config.remote.host], dir, () => fs.rmSync(dir, { recursive: true, force: true }));
 }
 
 /**
@@ -150,7 +158,7 @@ export async function withRunner(ctx, config, options, deps, body) {
   try {
     return await body(run, run.notes ?? []);
   } finally {
-    run.cleanup?.();
+    await run.cleanup?.();
   }
 }
 
@@ -174,7 +182,7 @@ function ciInputs(ctx) {
 const sshBlock = (alias, inputs) => [
   '', `Host ${alias}`, `  HostName ${inputs.host}`, `  User ${inputs.user}`, '  IdentityFile ~/.ssh/deploy_key',
   '  StrictHostKeyChecking yes', '  BatchMode yes', '  ConnectTimeout 20', '  ServerAliveInterval 30',
-  '  ControlMaster auto', '  ControlPath ~/.ssh/cm-%C', '  ControlPersist 15m', '',
+  '  ControlMaster auto', '  ControlPath ~/.ssh/cm-%C', '  ControlPersist 60', '',
 ].join('\n');
 
 /** CI transport: pinned key, known_hosts, ssh config block and DOCKER_HOST=ssh://<alias> in $GITHUB_ENV. */

package/stack/ssh-session.mjs

@@ -0,0 +1,178 @@
+// ssh-session.mjs - one command-owned connection; all processes use ctx.spawn. Windows prefers a Unix socket in private 0700 HOME
+// when runtime ssh -V reports OpenSSH >= 6.7 and a local AF_UNIX Docker CLI probe succeeds. Otherwise a fresh ephemeral TCP
+// port is asserted to bind only 127.0.0.1 and never reaches files or logs. Finally and SIGINT/SIGTERM close the tunnel.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { failure } from './errors.mjs';
+import { restrictToUser } from './private-file.mjs';
+
+const FREE_PORT = "const net=require('node:net');const s=net.createServer();s.on('error',()=>process.exit(1));s.listen(0,'127.0.0.1',()=>{console.log(s.address().port);s.close();});";
+const WAIT_PORT = "const net=require('node:net');const deadline=Date.now()+20000;function probe(){const s=net.connect({host:'127.0.0.1',port:Number(process.argv[1])});s.setTimeout(200);s.on('connect',()=>{s.destroy();process.exit(0);});function retry(){s.destroy();if(Date.now()>=deadline)process.exit(1);else setTimeout(probe,50);}s.on('error',retry);s.on('timeout',retry);}probe();";
+
+const WAIT_SOCKET = WAIT_PORT.replace("{host:'127.0.0.1',port:Number(process.argv[1])}", '{path:process.argv[1]}');
+const UNIX_PROBE = String.raw`
+const http = require('node:http');
+const fs = require('node:fs');
+const { spawn } = require('node:child_process');
+const socket = process.argv[1];
+let child;
+function finish(code) {
+  child?.kill();
+  server.close();
+  try { fs.unlinkSync(socket); } catch {}
+  process.exit(code);
+}
+const server = http.createServer((req, res) => {
+  res.setHeader('Api-Version', '1.47');
+  res.setHeader('Content-Type', 'application/json');
+  res.end(req.url.endsWith('/_ping') ? 'OK' : JSON.stringify({ Version: '27.0.0', ApiVersion: '1.47', MinAPIVersion: '1.24', Os: 'linux', Arch: 'amd64' }));
+});
+server.on('error', () => finish(1));
+server.listen(socket, () => {
+  child = spawn('docker', ['--host', 'unix://' + socket.replaceAll('\\', '/'), 'version', '--format', '{{.Server.Version}}'], { stdio: 'ignore', windowsHide: true });
+  child.on('error', () => finish(1));
+  child.on('exit', code => finish(code === 0 ? 0 : 1));
+});
+setTimeout(() => finish(1), 5000);
+`;
+
+/** TCP Docker forwarding must never expose the manager on a non-loopback interface. */
+function loopbackForward(bind, port, socket) {
+  if (bind !== '127.0.0.1') throw failure('STACK_SSH_SESSION', 'the Docker tunnel must bind 127.0.0.1');
+  return `${bind}:${port}:${socket}`;
+}
+
+function unixEndpoint(ctx, command, env) {
+  const version = ctx.spawn(command, ['-V'], { env });
+  const match = /OpenSSH(?:_for_Windows)?_(\d+)\.(\d+)/u.exec(`${version.stderr ?? ''} ${version.stdout ?? ''}`);
+  if (!successful(version) || !match || Number(match[1]) < 6 || Number(match[1]) === 6 && Number(match[2]) < 7) return null;
+  if (!env.HOME) return null;
+  fs.mkdirSync(env.HOME, { recursive: true, mode: 0o700 });
+  fs.chmodSync(env.HOME, 0o700);
+  restrictToUser(ctx, env.HOME, '(OI)(CI)F');
+  const probe = path.join(env.HOME, 'probe.sock');
+  try {
+    if (!successful(ctx.spawn(process.execPath, ['-e', UNIX_PROBE, probe], { env, timeout: 7000 }))) return null;
+  } finally {
+    fs.rmSync(probe, { force: true });
+  }
+  return path.join(env.HOME, 'docker.sock').replaceAll('\\', '/');
+}
+
+/** The same multiplexing settings belong to the master, remote commands and Docker's SSH alias. */
+export function controlSettings(controlPath) {
+  return ['ControlMaster=auto', `ControlPath=${controlPath}`, 'ControlPersist=60'];
+}
+
+function successful(result) {
+  return !result.error && result.status === 0;
+}
+
+function freePort(ctx) {
+  const result = ctx.spawn(process.execPath, ['-e', FREE_PORT]);
+  const port = Number(result.stdout?.trim());
+  if (!successful(result) || !Number.isInteger(port) || port < 1 || port > 65535) throw failure('STACK_SSH_SESSION', 'cannot allocate a loopback port');
+  return port;
+}
+
+/** Waits for the tunnel child to exit before any private credentials are removed. */
+function stopTunnel(child) {
+  if (!child || child.spawnError || child.exitCode !== null && child.exitCode !== undefined || child.signalCode) return;
+  if (!child.once) { child.kill(); return; }
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => child.kill('SIGKILL'), 2000);
+    child.once('close', () => { clearTimeout(timer); resolve(); });
+    child.kill();
+  });
+}
+
+async function closeTunnel(child, cleanup) {
+  try { await stopTunnel(child); } finally { cleanup(); }
+}
+
+/** Creates a lazy connection; no SSH is spawned until a Docker query or remote command needs it. */
+export function createSshSession(ctx, { argv, env = ctx.env, controlPath, socket = '/var/run/docker.sock', cleanup = () => {} }) {
+  const windows = (ctx.platform ?? process.platform) === 'win32';
+  const [command, ...head] = argv;
+  const controls = windows ? [] : controlSettings(controlPath).flatMap((setting) => ['-o', setting]);
+  let started = false;
+  let ready = false;
+  let child;
+  let host;
+  let closing;
+  const signalHandlers = new Map();
+  let closed = false;
+
+  function start() {
+    if (closed) throw failure('STACK_SSH_SESSION', 'the command session is already closed');
+    if (ready) return;
+    if (started) throw failure('STACK_SSH_SESSION', 'the SSH connection failed to open');
+    started = true;
+    if (windows) {
+      const localSocket = unixEndpoint(ctx, command, env);
+      const port = localSocket ? null : freePort(ctx);
+      const forward = localSocket ? `./docker.sock:${socket}` : loopbackForward('127.0.0.1', port, socket);
+      host = localSocket ? `unix://${localSocket}` : `tcp://127.0.0.1:${port}`;
+      child = ctx.spawn(command, ['-N', '-o', 'ExitOnForwardFailure=yes', '-o', 'GatewayPorts=no', ...(localSocket ? ['-o', 'StreamLocalBindMask=0177'] : []), '-L', forward, ...head], { env, cwd: localSocket ? env.HOME : undefined, background: true });
+      if (typeof child?.kill !== 'function') {
+        child = undefined;
+        throw failure('STACK_SSH_SESSION', 'cannot start the Docker SSH tunnel');
+      }
+      installSignals();
+      const probeArgs = localSocket ? ['-e', WAIT_SOCKET, localSocket] : ['-e', WAIT_PORT, String(port)];
+      const probe = ctx.spawn(process.execPath, probeArgs, { env, timeout: 25000 });
+      if (!successful(probe)) throw failure('STACK_SSH_SESSION', 'the Docker SSH tunnel did not become ready');
+    } else {
+      const result = ctx.spawn(command, ['-MNf', ...controls, ...head], { env });
+      if (!successful(result)) throw failure('STACK_SSH_SESSION', 'cannot open the SSH control master');
+    }
+    ready = true;
+  }
+
+  function remote(remoteCommand, options = {}) {
+    // Windows cannot multiplex exec channels; Docker queries share the tunnel and remote scripts remain one call per step.
+    if (!windows) start();
+    return ctx.spawn(command, [...controls, ...head, remoteCommand], { ...options, env });
+  }
+
+  function dockerHost(alias) {
+    start();
+    return windows ? host : `ssh://${alias}`;
+  }
+
+  function installSignals() {
+    for (const [signal, code] of [['SIGINT', 130], ['SIGTERM', 143]]) {
+      const handler = () => { Promise.resolve(close()).finally(() => process.exit(code)); };
+      signalHandlers.set(signal, handler);
+      process.once(signal, handler);
+    }
+  }
+
+  function finish() {
+    for (const [signal, handler] of signalHandlers) process.removeListener(signal, handler);
+    signalHandlers.clear();
+    cleanup();
+  }
+
+  function close() {
+    if (closed) return closing;
+    closed = true;
+    if (windows && child) {
+      closing = closeTunnel(child, finish);
+      return closing;
+    }
+    try {
+      if (!windows && started) ctx.spawn(command, ['-O', 'exit', ...controls, ...head], { env });
+    } finally {
+      finish();
+    }
+  }
+
+  return { remote, dockerHost, close };
+}
+
+/** A short private directory for an invocation whose SSH credentials already live in the operator or CI HOME. */
+export function sessionDirectory() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'sc-'));
+}