openship 0.2.3 → 0.4.0

package/dist/chunk-E77LJWJK.js

@@ -0,0 +1,1535 @@
+import {
+  LocalExecutor
+} from "./chunk-U2DPZSXA.js";
+import {
+  connectSshClient,
+  getTarCreateEnv,
+  openSftp,
+  openSshUnixSocket,
+  prepareSourceTarArgs,
+  reconcileKnownHosts
+} from "./chunk-4MG3BVHE.js";
+import {
+  SshDisconnectedError
+} from "./chunk-4LEL3H2Z.js";
+import {
+  emitBufferedLines,
+  flushBufferedLines,
+  hasLocalCommand,
+  logEntry,
+  sq
+} from "./chunk-4CQWT2WL.js";
+import {
+  TRANSFER_EXCLUDES,
+  formatBytes,
+  safeErrorMessage
+} from "./chunk-JZLNHGLW.js";
+
+// ../../packages/adapters/src/system/executor.ts
+import { readFileSync } from "fs";
+
+// ../../packages/adapters/src/system/ssh-executor.ts
+import { createReadStream } from "fs";
+import { mkdtemp as mkdtemp2, rm as fsRm2, stat } from "fs/promises";
+import { tmpdir as tmpdir2 } from "os";
+import { dirname, join as join2 } from "path";
+
+// ../../packages/adapters/src/system/remote-transfer.ts
+import { spawn } from "child_process";
+import { createWriteStream } from "fs";
+import { chmod, mkdtemp, rm as fsRm, writeFile as fsWriteFile } from "fs/promises";
+import { tmpdir } from "os";
+import { join } from "path";
+function packLocalArchive(tarArgs, outFile) {
+  return new Promise((resolve, reject) => {
+    const tar = spawn("tar", tarArgs, { stdio: ["ignore", "pipe", "pipe"], env: getTarCreateEnv() });
+    const out = createWriteStream(outFile);
+    let stderr = "";
+    let tarCode = null;
+    let tarClosed = false;
+    let outClosed = false;
+    const settle = () => {
+      if (!tarClosed || !outClosed) return;
+      if (tarCode === 0) resolve();
+      else reject(new Error(`tar failed (exit ${tarCode})${stderr.trim() ? `: ${stderr.trim().slice(-300)}` : ""}`));
+    };
+    tar.stderr.on("data", (d) => {
+      stderr += d.toString();
+    });
+    tar.on("error", reject);
+    out.on("error", reject);
+    tar.stdout.pipe(out);
+    tar.on("close", (code) => {
+      tarCode = code ?? 1;
+      tarClosed = true;
+      settle();
+    });
+    out.on("finish", () => {
+      outClosed = true;
+      settle();
+    });
+  });
+}
+async function extractRemoteArchive(exec, remoteArchive, remotePath, expectedBytes, onLog) {
+  const received = Number((await exec(`wc -c < ${sq(remoteArchive)}`)).trim());
+  if (received !== expectedBytes) {
+    await exec(`rm -f ${sq(remoteArchive)}`).catch(() => {
+    });
+    throw new Error(`upload truncated: sent ${expectedBytes} bytes, server received ${received}`);
+  }
+  await exec(
+    `mkdir -p ${sq(remotePath)} && tar xzf ${sq(remoteArchive)} -C ${sq(remotePath)}; rc=$?; rm -f ${sq(remoteArchive)}; exit $rc`
+  );
+  onLog?.(logEntry(`Transferred ${formatBytes(expectedBytes)} and extracted on the server.`));
+}
+async function canUseRemoteRsync(deps) {
+  if (deps.config.privateKey && deps.config.privateKeyPassphrase && !deps.config.sshAgent) {
+    return { ok: false, reason: "encrypted SSH keys without an agent are not supported by non-interactive rsync" };
+  }
+  const [localRsync, localSsh, localSshpass, remoteRsync] = await Promise.all([
+    hasLocalCommand("rsync"),
+    hasLocalCommand("ssh"),
+    deps.config.password ? hasLocalCommand("sshpass") : Promise.resolve(true),
+    deps.hasRemoteCommand("rsync")
+  ]);
+  if (!localRsync) return { ok: false, reason: "local rsync is not installed" };
+  if (!localSsh) return { ok: false, reason: "local ssh is not installed" };
+  if (!localSshpass) return { ok: false, reason: "local sshpass is not installed for password-based rsync" };
+  if (!remoteRsync) return { ok: false, reason: "remote rsync is not installed" };
+  return { ok: true };
+}
+function buildRsyncSshCommand(config, keyPath) {
+  const args = config.password ? [
+    "sshpass",
+    "-e",
+    "ssh",
+    "-p",
+    String(config.port ?? 22),
+    "-o",
+    "NumberOfPasswordPrompts=1",
+    "-o",
+    "PreferredAuthentications=password,keyboard-interactive",
+    "-o",
+    "PubkeyAuthentication=no",
+    "-o",
+    "StrictHostKeyChecking=accept-new"
+  ] : [
+    "ssh",
+    "-p",
+    String(config.port ?? 22),
+    "-o",
+    "BatchMode=yes",
+    "-o",
+    "StrictHostKeyChecking=accept-new"
+  ];
+  if (config.sshAgent) {
+    args.push("-A");
+  }
+  if (keyPath) {
+    args.push("-i", keyPath, "-o", "IdentitiesOnly=yes");
+  }
+  return args.map(sq).join(" ");
+}
+async function withTemporaryPrivateKey(config, fn) {
+  if (!config.privateKey || config.sshAgent) {
+    return fn();
+  }
+  const tempDir = await mkdtemp(join(tmpdir(), "openship-rsync-key-"));
+  const keyPath = join(tempDir, "id_rsa");
+  try {
+    await fsWriteFile(keyPath, config.privateKey);
+    await chmod(keyPath, 384);
+    return await fn(keyPath);
+  } finally {
+    await fsRm(tempDir, { recursive: true, force: true }).catch(() => {
+    });
+  }
+}
+async function runRsync(config, args, onLog, cwd) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn("rsync", args, {
+      cwd,
+      env: {
+        ...getTarCreateEnv(),
+        ...config.password ? { SSHPASS: config.password } : {}
+      },
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    const stdoutState = { partial: "" };
+    const stderrState = { partial: "" };
+    proc.stdout.on("data", (chunk) => {
+      emitBufferedLines(chunk, stdoutState, (line) => onLog?.(logEntry(line)));
+    });
+    proc.stderr.on("data", (chunk) => {
+      emitBufferedLines(chunk, stderrState, (line) => onLog?.(logEntry(line)));
+    });
+    proc.on("error", (err) => {
+      reject(new Error(`rsync failed to start: ${err.message}`));
+    });
+    proc.on("close", (code) => {
+      flushBufferedLines(stdoutState, (line) => onLog?.(logEntry(line)));
+      flushBufferedLines(stderrState, (line) => onLog?.(logEntry(line)));
+      resolve({ code: code ?? 1 });
+    });
+  });
+}
+async function uploadFileWithRsync(localFile, remoteFile, deps, onLog, opts) {
+  await reconcileKnownHosts(deps.config);
+  const retries = Math.max(1, opts?.retries ?? 3);
+  const host = deps.config.host.includes(":") ? `[${deps.config.host}]` : deps.config.host;
+  const user = deps.config.username ?? "root";
+  const target = `${user}@${host}:${remoteFile}`;
+  await withTemporaryPrivateKey(deps.config, async (keyPath) => {
+    let lastCode = 1;
+    for (let attempt = 1; attempt <= retries; attempt++) {
+      if (attempt > 1) {
+        onLog?.(logEntry(`Connection dropped \u2014 resuming upload (attempt ${attempt}/${retries})...`, "warn"));
+      }
+      const args = [
+        "-a",
+        // already gzipped, so no `-z`
+        "--partial",
+        // keep the partial on interruption; delta-resume on re-run
+        "--progress",
+        "--timeout=60",
+        // abort if no I/O for 60s → surfaces a stall as a retryable exit
+        "-e",
+        buildRsyncSshCommand(deps.config, keyPath),
+        localFile,
+        target
+      ];
+      const { code } = await runRsync(deps.config, args, onLog);
+      if (code === 0) return;
+      lastCode = code;
+    }
+    throw new Error(`rsync upload failed after ${retries} attempt(s) (exit ${lastCode})`);
+  });
+}
+
+// ../../packages/adapters/src/system/ssh-executor.ts
+function clampWindow(value, fallback, min, max) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  return Math.max(min, Math.min(max, Math.floor(value)));
+}
+var SshExecutor = class _SshExecutor {
+  client = null;
+  connecting = null;
+  /** One shared SFTP subsystem channel per client — see sftp(). */
+  sftpChannel = null;
+  config;
+  /** Subscribers notified when the transport drops (see onDisconnect). */
+  disconnectListeners = /* @__PURE__ */ new Set();
+  /** In-flight cancelable ops — each entry aborts ONE exec/stream on a drop,
+   *  so a dead channel fails fast instead of hanging to its command timeout. */
+  inflight = /* @__PURE__ */ new Set();
+  /** Reverse-forward handlers keyed by the remote bound port (see reverseForward). */
+  reverseHandlers = /* @__PURE__ */ new Map();
+  /** The client the single 'tcp connection' dispatcher is attached to (re-attached on reconnect). */
+  reverseListenerClient = null;
+  constructor(config) {
+    if (!config.privateKey && !config.sshAgent && !config.password) {
+      throw new Error("SSH requires one of privateKey, sshAgent, or password.");
+    }
+    this.config = config;
+  }
+  async connect() {
+    if (this.client) return this.client;
+    if (this.connecting) return this.connecting;
+    this.connecting = (async () => {
+      const client = await connectSshClient(this.config);
+      const onTransportDown = (cause) => {
+        if (this.client !== client) return;
+        this.client = null;
+        this.sftpChannel = null;
+        this.handleDisconnect(cause);
+      };
+      client.on("close", () => onTransportDown());
+      client.on("end", () => onTransportDown());
+      client.on("error", (err) => onTransportDown(err));
+      this.client = client;
+      this.connecting = null;
+      return client;
+    })();
+    return this.connecting;
+  }
+  /**
+   * Subscribe to transport-level disconnects. Returns an unsubscribe fn.
+   */
+  onDisconnect(cb) {
+    this.disconnectListeners.add(cb);
+    return () => {
+      this.disconnectListeners.delete(cb);
+    };
+  }
+  /**
+   * The transport died. Reject every in-flight exec/stream with a typed
+   * SshDisconnectedError — so they fail in <1s instead of hanging to their
+   * per-command timeout on a dead channel — then notify subscribers so the
+   * manager can reconnect / re-drive journaled ops.
+   */
+  handleDisconnect(cause) {
+    const err = new SshDisconnectedError(
+      cause?.message ? `SSH connection lost: ${cause.message}` : "SSH connection lost"
+    );
+    const aborts = [...this.inflight];
+    this.inflight.clear();
+    for (const abort of aborts) {
+      try {
+        abort(err);
+      } catch {
+      }
+    }
+    for (const cb of [...this.disconnectListeners]) {
+      try {
+        cb(err);
+      } catch {
+      }
+    }
+  }
+  /**
+   * One SFTP subsystem channel per client, opened lazily and shared by every
+   * file op. ssh2's SFTPWrapper pipelines many concurrent requests over a
+   * single channel, so file operations cost exactly ONE session against the
+   * server's MaxSessions — not one channel per op, which leaks and exhausts
+   * the quota, then takes down the whole connection (incl. a live build) on
+   * the next channel-open failure (#34). Self-clears on the channel's own
+   * close/error and on resetConnection/dispose so the next op reopens clean.
+   */
+  async sftp() {
+    const client = await this.connect();
+    if (this.sftpChannel) return this.sftpChannel;
+    const opening = openSftp(client).then((wrapper) => {
+      const drop = () => {
+        if (this.sftpChannel === opening) this.sftpChannel = null;
+      };
+      wrapper.once("close", drop);
+      wrapper.once("error", drop);
+      return wrapper;
+    });
+    opening.catch(() => {
+      if (this.sftpChannel === opening) this.sftpChannel = null;
+    });
+    this.sftpChannel = opening;
+    return opening;
+  }
+  /** Close + forget the shared SFTP channel (frees its session) without
+   *  touching the SSH client, so file ops can reopen on the same connection. */
+  dropSftp() {
+    const ch = this.sftpChannel;
+    this.sftpChannel = null;
+    if (ch) ch.then((w) => {
+      try {
+        w.end();
+      } catch {
+      }
+    }).catch(() => {
+    });
+  }
+  /**
+   * Force-close the current connection so the next call reconnects.
+   */
+  resetConnection() {
+    this.dropSftp();
+    if (this.client) {
+      try {
+        this.client.end();
+      } catch {
+      }
+      this.client = null;
+    }
+    this.connecting = null;
+  }
+  /**
+   * Recover from a channel-open failure without killing live work. If other
+   * ops are still streaming on this connection (a docker build, an exec), the
+   * failure is session pressure — NOT a dead socket — so ending the client
+   * would abort that in-flight command (#34). Free the SFTP channel and keep
+   * the connection. With nothing in flight the cached socket is stale (idle
+   * drop), so reset it fully.
+   */
+  recoverFromChannelError() {
+    if (this.inflight.size > 0) this.dropSftp();
+    else this.resetConnection();
+  }
+  /** Returns true if the error is an SSH channel-open failure. */
+  static isChannelError(err) {
+    if (!(err instanceof Error)) return false;
+    const msg = err.message.toLowerCase();
+    return msg.includes("channel open failure") || msg.includes("open failed");
+  }
+  /**
+   * Run an operation, and if it fails opening an SSH channel on a half-dead
+   * cached connection ("Channel open failure: open failed" — common after the
+   * idle timeout drops the socket), drop the connection and retry ONCE on a
+   * fresh one. This is why `exec` survives a stale connection; the SFTP-based
+   * ops (writeFile/readFile/exists) must go through it too, or a deploy's route
+   * write fails spuriously and only succeeds on a manual redeploy.
+   */
+  async withChannelRetry(fn) {
+    try {
+      return await fn();
+    } catch (err) {
+      if (_SshExecutor.isChannelError(err)) {
+        this.recoverFromChannelError();
+        return fn();
+      }
+      throw err;
+    }
+  }
+  async exec(command, opts) {
+    return this.withChannelRetry(() => this._exec(command, opts));
+  }
+  /** Prefix applied to every SSH command - keeps dpkg non-interactive. */
+  static ENV_PREFIX = "export DEBIAN_FRONTEND=noninteractive DPKG_FORCE=confnew && ";
+  async _exec(command, opts) {
+    const client = await this.connect();
+    const timeout = opts?.timeout ?? 3e4;
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      let timer = null;
+      const abort = (err) => finish(() => reject(err));
+      const finish = (act) => {
+        if (settled) return;
+        settled = true;
+        if (timer) clearTimeout(timer);
+        this.inflight.delete(abort);
+        act();
+      };
+      this.inflight.add(abort);
+      timer = setTimeout(
+        () => finish(() => reject(new Error(`Command timed out after ${timeout}ms: ${command}`))),
+        timeout
+      );
+      client.exec(_SshExecutor.ENV_PREFIX + command, (err, stream) => {
+        if (err) return finish(() => reject(err));
+        let stdout = "";
+        let stderr = "";
+        stream.on("data", (data) => {
+          stdout += data.toString();
+        });
+        stream.stderr.on("data", (data) => {
+          stderr += data.toString();
+        });
+        stream.on("close", (code) => {
+          finish(() => {
+            if (code !== 0) {
+              const detail = [stderr.trim(), stdout.trim()].filter(Boolean).join("\n");
+              reject(new Error(detail || `Exit code ${code}`));
+            } else resolve(stdout.trim());
+          });
+        });
+      });
+    });
+  }
+  streamExec(command, onLog) {
+    return this._streamExec(command, onLog).catch((err) => {
+      if (_SshExecutor.isChannelError(err)) {
+        this.recoverFromChannelError();
+        return this._streamExec(command, onLog);
+      }
+      throw err;
+    });
+  }
+  async _streamExec(command, onLog) {
+    const client = await this.connect();
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const abort = (err) => finish(() => reject(err));
+      const finish = (act) => {
+        if (settled) return;
+        settled = true;
+        this.inflight.delete(abort);
+        act();
+      };
+      this.inflight.add(abort);
+      client.exec(_SshExecutor.ENV_PREFIX + command, (err, stream) => {
+        if (err) return finish(() => reject(err));
+        const chunks = [];
+        const onChunk = (data, level) => {
+          const text = data.toString();
+          if (!text) return;
+          chunks.push(text);
+          onLog(logEntry(text, level, data.toString("base64")));
+        };
+        stream.on("data", (data) => onChunk(data, "info"));
+        stream.stderr.on("data", (data) => onChunk(data, "warn"));
+        let exitCode = null;
+        stream.on("exit", (code) => {
+          exitCode = code;
+        });
+        stream.on("close", (code) => {
+          finish(() => {
+            const final = typeof code === "number" ? code : exitCode;
+            if (final == null) {
+              reject(
+                new Error(
+                  "remote channel closed without an exit status \u2014 the SSH connection or channel was terminated mid-command"
+                )
+              );
+            } else {
+              resolve({ code: final, output: chunks.join("") });
+            }
+          });
+        });
+      });
+    });
+  }
+  async writeFile(path, content) {
+    const dir = dirname(path);
+    try {
+      await this.exec(`mkdir -p ${sq(dir)}`);
+    } catch {
+    }
+    return this.withChannelRetry(async () => {
+      const sftp = await this.sftp();
+      return new Promise((resolve, reject) => {
+        sftp.writeFile(path, content, { encoding: "utf-8" }, (err) => {
+          if (err) reject(err);
+          else resolve();
+        });
+      });
+    });
+  }
+  async readFile(path) {
+    return this.withChannelRetry(async () => {
+      const sftp = await this.sftp();
+      return new Promise((resolve, reject) => {
+        sftp.readFile(path, { encoding: "utf-8" }, (err, data) => {
+          if (err) reject(err);
+          else resolve(data.toString());
+        });
+      });
+    });
+  }
+  async exists(path) {
+    return this.withChannelRetry(async () => {
+      const sftp = await this.sftp();
+      return new Promise((resolve) => {
+        sftp.stat(path, (err) => {
+          resolve(!err);
+        });
+      });
+    });
+  }
+  async mkdir(path) {
+    await this.exec(`mkdir -p ${sq(path)}`);
+  }
+  async rm(path) {
+    try {
+      await this.exec(`rm -rf ${sq(path)}`);
+    } catch {
+    }
+  }
+  rawExec(command) {
+    return (async () => {
+      const client = await this.connect();
+      return new Promise((resolve, reject) => {
+        client.exec(command, (err, stream) => {
+          if (err) return reject(err);
+          const onClose = new Promise((res) => {
+            stream.on("close", (code) => res(code ?? 1));
+          });
+          resolve({
+            stdout: stream,
+            stderr: stream.stderr,
+            onClose,
+            kill: () => {
+              try {
+                stream.close();
+              } catch {
+              }
+            }
+          });
+        });
+      });
+    })();
+  }
+  /**
+   * Pipe `body` into a remote command's stdin over a raw ssh2 channel, half-
+   * closing stdin at EOF. The streaming inverse of rawExec: used to stream a
+   * `docker save` tar straight into `docker load` on another host without
+   * staging the (multi-GB) image to a temp file. Bounded stderr tail for
+   * diagnostics; registered for transport-drop abort like _exec/_streamExec.
+   */
+  execWithInput(command, body) {
+    return (async () => {
+      const client = await this.connect();
+      return new Promise((resolve, reject) => {
+        let settled = false;
+        const abort = (err) => finish(() => reject(err));
+        const finish = (act) => {
+          if (settled) return;
+          settled = true;
+          this.inflight.delete(abort);
+          act();
+        };
+        this.inflight.add(abort);
+        client.exec(command, (err, stream) => {
+          if (err) return finish(() => reject(err));
+          let stderr = "";
+          stream.stderr.on("data", (d) => {
+            stderr += d.toString();
+            if (stderr.length > 16 * 1024) stderr = stderr.slice(-16 * 1024);
+          });
+          let stdout = "";
+          stream.on("data", (d) => {
+            stdout += d.toString();
+            if (stdout.length > 16 * 1024) stdout = stdout.slice(-16 * 1024);
+          });
+          let exitCode = null;
+          stream.on("exit", (code) => {
+            exitCode = code;
+          });
+          stream.on("close", (code) => {
+            finish(() => {
+              const final = typeof code === "number" ? code : exitCode;
+              if (final == null) {
+                reject(
+                  new Error(
+                    "remote channel closed without an exit status \u2014 the SSH connection was terminated mid-command"
+                  )
+                );
+              } else {
+                resolve({ code: final, stderr: stderr.trim(), stdout: stdout.trim() });
+              }
+            });
+          });
+          body.on("error", (e) => finish(() => {
+            try {
+              stream.close();
+            } catch {
+            }
+            reject(e);
+          }));
+          stream.on("error", (e) => finish(() => reject(e)));
+          body.pipe(stream);
+        });
+      });
+    })();
+  }
+  /**
+   * Open an interactive PTY shell on the remote host. The returned
+   * ShellSession wraps an ssh2 ClientChannel: writes go to stdin,
+   * stdout/stderr emit on the readable streams, setWindow forwards to
+   * channel.setWindow, close ends the channel. Lifetime is bound to the
+   * channel - the underlying ssh2.Client stays cached by sshManager, so
+   * callers must wrap with `sshManager.retain(serverId)` / `release()`
+   * to avoid the 5-minute idle drop on the parent connection.
+   */
+  async openShell(opts) {
+    const client = await this.connect();
+    const cols = clampWindow(opts?.cols, 80, 1, 1e3);
+    const rows = clampWindow(opts?.rows, 24, 1, 500);
+    const term = opts?.term || "xterm-256color";
+    const channel = await new Promise(
+      (resolve, reject) => {
+        client.shell(
+          { term, cols, rows, width: 0, height: 0, modes: {} },
+          (err, ch) => err ? reject(err) : resolve(ch)
+        );
+      }
+    );
+    const closeListeners = [];
+    let closed = false;
+    const fireClose = (code, signal) => {
+      if (closed) return;
+      closed = true;
+      for (const cb of closeListeners) {
+        try {
+          cb(code, signal);
+        } catch {
+        }
+      }
+    };
+    channel.on("exit", (code, signal) => {
+      fireClose(code, signal);
+    });
+    channel.on("close", () => fireClose(null));
+    channel.on("error", () => fireClose(null));
+    return {
+      stdin: channel,
+      stdout: channel,
+      stderr: channel.stderr,
+      setWindow: (c, r) => {
+        const sc = clampWindow(c, 80, 1, 1e3);
+        const sr = clampWindow(r, 24, 1, 500);
+        try {
+          channel.setWindow(sr, sc, 0, 0);
+        } catch {
+        }
+      },
+      close: (_signal) => {
+        try {
+          channel.end();
+        } catch {
+        }
+        try {
+          channel.close();
+        } catch {
+        }
+      },
+      onClose: (cb) => {
+        closeListeners.push(cb);
+      }
+    };
+  }
+  async forwardUnixSocket(socketPath) {
+    const client = await this.connect();
+    return openSshUnixSocket(client, socketPath);
+  }
+  /**
+   * Carry the Docker Engine API over a `docker system dial-stdio` exec channel
+   * on the pooled connection — the streamlocal-free transport used when the
+   * SSH server (or the Bun-compiled desktop runtime) can't do socket
+   * forwarding. Uses the SAME ENV_PREFIX as streamExec so `docker` resolves on
+   * PATH exactly as it does for the remote build (which is proven to work).
+   */
+  async openDockerDialStdio() {
+    const client = await this.connect();
+    return new Promise((resolve, reject) => {
+      client.exec(_SshExecutor.ENV_PREFIX + "docker system dial-stdio", (err, stream) => {
+        if (err) return reject(err);
+        stream.stderr?.on("data", (d) => {
+          const text = d.toString().trim();
+          if (text) console.warn(`[docker-ssh] dial-stdio stderr: ${text}`);
+        });
+        stream.on("exit", (code) => {
+          if (code) console.warn(`[docker-ssh] dial-stdio exited early (code=${code})`);
+        });
+        resolve(stream);
+      });
+    });
+  }
+  async forwardPort(remoteHost, remotePort) {
+    const client = await this.connect();
+    return new Promise((resolve, reject) => {
+      client.forwardOut(
+        "127.0.0.1",
+        0,
+        remoteHost,
+        remotePort,
+        (err, stream) => {
+          if (err) return reject(err);
+          resolve(stream);
+        }
+      );
+    });
+  }
+  /**
+   * Open a reverse tunnel: the remote listens on an ephemeral 127.0.0.1 port
+   * and every connection to it is handed to `onConnection` as a duplex stream
+   * over this SSH connection. ssh2's 'tcp connection' event is client-wide, so
+   * a single dispatcher routes by the bound `destPort` to the right handler.
+   */
+  async reverseForward(onConnection) {
+    const client = await this.connect();
+    this.attachReverseListener(client);
+    const port = await new Promise((resolve, reject) => {
+      client.forwardIn("127.0.0.1", 0, (err, boundPort) => {
+        if (err) return reject(err);
+        resolve(boundPort);
+      });
+    });
+    this.reverseHandlers.set(port, onConnection);
+    return {
+      port,
+      close: async () => {
+        this.reverseHandlers.delete(port);
+        await new Promise((resolve) => {
+          try {
+            client.unforwardIn("127.0.0.1", port, () => resolve());
+          } catch {
+            resolve();
+          }
+        });
+      }
+    };
+  }
+  /** Attach the single client-wide 'tcp connection' dispatcher (idempotent per client). */
+  attachReverseListener(client) {
+    if (this.reverseListenerClient === client) return;
+    this.reverseListenerClient = client;
+    client.on("tcp connection", (details, accept, reject) => {
+      const handler = this.reverseHandlers.get(details.destPort);
+      if (!handler) {
+        try {
+          reject();
+        } catch {
+        }
+        return;
+      }
+      const channel = accept();
+      handler(channel);
+    });
+  }
+  async dispose() {
+    this.connecting = null;
+    this.sftpChannel = null;
+    this.reverseHandlers.clear();
+    this.reverseListenerClient = null;
+    if (this.client) {
+      this.client.end();
+      this.client = null;
+    }
+  }
+  async transferIn(localPath, remotePath, onLog, options) {
+    const deps = { config: this.config, hasRemoteCommand: (c) => this.hasRemoteCommand(c) };
+    const excludes = options?.excludes ?? [...TRANSFER_EXCLUDES];
+    const { args: tarArgs, cleanup: cleanupTarList } = await prepareSourceTarArgs(localPath, {
+      excludes,
+      includes: options?.includes,
+      alsoInclude: options?.alsoInclude
+    });
+    const tmpLocalDir = await mkdtemp2(join2(tmpdir2(), "openship-xfer-"));
+    const localArchive = join2(tmpLocalDir, "context.tar.gz");
+    const remoteArchive = `${remotePath}.openship-xfer.tar.gz`;
+    try {
+      onLog?.(logEntry("Packing source into a single archive..."));
+      await packLocalArchive(tarArgs, localArchive);
+      const totalBytes = (await stat(localArchive)).size;
+      await this.exec(`mkdir -p ${sq(dirname(remoteArchive))}`);
+      const rsync = await canUseRemoteRsync(deps);
+      if (rsync.ok) {
+        onLog?.(logEntry(`Uploading ${formatBytes(totalBytes)} archive via rsync (resumable)...`));
+        await uploadFileWithRsync(localArchive, remoteArchive, deps, onLog);
+      } else {
+        onLog?.(
+          logEntry(`Uploading ${formatBytes(totalBytes)} archive via SFTP (resumable) \u2014 ${rsync.reason}.`)
+        );
+        await this.sftpUploadResumable(localArchive, remoteArchive, totalBytes, onLog);
+      }
+      await extractRemoteArchive((command) => this.exec(command), remoteArchive, remotePath, totalBytes, onLog);
+    } finally {
+      await cleanupTarList().catch(() => {
+      });
+      await fsRm2(tmpLocalDir, { recursive: true, force: true }).catch(() => {
+      });
+    }
+  }
+  async hasRemoteCommand(command) {
+    try {
+      await this.exec(`command -v ${command} >/dev/null 2>&1 && echo ok`, { timeout: 5e3 });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Resumable SFTP upload (the fallback when rsync isn't available — password
+   * auth with no `sshpass`). Each attempt `stat`s the remote to learn how much
+   * already landed and streams the REST from that offset (append), so a dropped
+   * or stalled connection continues instead of restarting from 0. A watchdog
+   * aborts the attempt if no bytes flow for `STALL_MS`, and the loop retries
+   * (resuming) up to `MAX_ATTEMPTS`.
+   */
+  async sftpUploadResumable(localArchive, remoteArchive, totalBytes, onLog) {
+    const MAX_ATTEMPTS = 4;
+    const STALL_MS = 3e4;
+    let lastErr = null;
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+      const sftp = await this.sftp();
+      let offset = 0;
+      try {
+        const size = await new Promise(
+          (resolve, reject) => sftp.stat(remoteArchive, (err, stats) => err ? reject(err) : resolve(stats.size))
+        );
+        if (size === totalBytes) return;
+        if (size < totalBytes) offset = size;
+      } catch {
+        offset = 0;
+      }
+      if (attempt > 1 || offset > 0) {
+        onLog?.(
+          logEntry(
+            `Resuming SFTP upload from ${formatBytes(offset)} (attempt ${attempt}/${MAX_ATTEMPTS})...`,
+            "warn"
+          )
+        );
+      }
+      try {
+        await this.sftpStreamFrom(sftp, localArchive, remoteArchive, offset, totalBytes, STALL_MS, onLog);
+        return;
+      } catch (err) {
+        lastErr = err instanceof Error ? err : new Error(String(err));
+        onLog?.(logEntry(`SFTP upload interrupted: ${lastErr.message}`, "warn"));
+      }
+    }
+    throw lastErr ?? new Error("SFTP upload failed");
+  }
+  /** Stream `localArchive` (from `offset`) into `remoteArchive`, appending when
+   *  resuming. Rejects on error, on a stall (no bytes for `stallMs`), or if the
+   *  stream closes before `totalBytes` land. */
+  sftpStreamFrom(sftp, localArchive, remoteArchive, offset, totalBytes, stallMs, onLog) {
+    return new Promise((resolve, reject) => {
+      const read = createReadStream(localArchive, { start: offset });
+      const write = sftp.createWriteStream(remoteArchive, { flags: offset > 0 ? "a" : "w" });
+      let transferred = offset;
+      let lastProgressAt = Date.now();
+      const startedAt = Date.now();
+      let lastReportedAt = startedAt;
+      let settled = false;
+      const finish = (fn) => {
+        if (settled) return;
+        settled = true;
+        clearInterval(watch);
+        fn();
+      };
+      const watch = setInterval(() => {
+        if (Date.now() - lastProgressAt > stallMs) {
+          read.destroy();
+          write.end();
+          finish(() => reject(new Error(`stalled \u2014 no data for ${Math.round(stallMs / 1e3)}s`)));
+        }
+      }, 5e3);
+      watch.unref?.();
+      read.on("data", (chunk) => {
+        transferred += chunk.length;
+        lastProgressAt = Date.now();
+        const now = Date.now();
+        if (now - lastReportedAt >= 2500) {
+          lastReportedAt = now;
+          const elapsed = (now - startedAt) / 1e3;
+          const mbps = elapsed > 0 ? (transferred - offset) / 1024 / 1024 / elapsed : 0;
+          const pct = totalBytes > 0 ? Math.min(Math.floor(transferred / totalBytes * 100), 100) : 0;
+          onLog?.(logEntry(`  ~${pct}% \xB7 ${formatBytes(transferred)} \xB7 ${mbps.toFixed(1)} MB/s`));
+        }
+      });
+      read.on("error", (e) => finish(() => reject(e)));
+      write.on("error", (e) => finish(() => reject(e)));
+      write.on(
+        "close",
+        () => finish(
+          () => transferred >= totalBytes ? resolve() : reject(new Error(`incomplete upload: ${transferred}/${totalBytes} bytes`))
+        )
+      );
+      read.pipe(write);
+    });
+  }
+};
+
+// ../../packages/adapters/src/system/system-ssh-executor.ts
+import { execFile as execFile2, spawn as spawn2 } from "child_process";
+import { once } from "events";
+import { mkdtemp as mkdtemp3, rm as fsRm3, stat as stat2, unlink } from "fs/promises";
+import { connect as netConnect } from "net";
+import { tmpdir as tmpdir3 } from "os";
+import { dirname as dirname2, join as join3 } from "path";
+import { Duplex } from "stream";
+import { promisify as promisify2 } from "util";
+import { randomBytes as randomBytes2 } from "crypto";
+
+// ../../packages/adapters/src/system/system-ssh.ts
+import { randomBytes } from "crypto";
+var CONNECT_TIMEOUT_SECONDS = 15;
+function makeControlPath() {
+  return `/tmp/openship-ssh-${process.pid}-${randomBytes(6).toString("hex")}.sock`;
+}
+function buildBaseSshArgs(config, controlPath) {
+  const args = [
+    "-p",
+    String(config.port ?? 22),
+    // BatchMode keeps the OS ssh non-interactive: agent/keys only, never a
+    // password/passphrase prompt that would hang a headless API process.
+    "-o",
+    "BatchMode=yes",
+    "-o",
+    "StrictHostKeyChecking=accept-new",
+    "-o",
+    `ConnectTimeout=${CONNECT_TIMEOUT_SECONDS}`,
+    "-o",
+    "ServerAliveInterval=15",
+    "-o",
+    "ServerAliveCountMax=3",
+    // One authenticated master; subsequent ssh calls attach to it.
+    "-o",
+    "ControlMaster=auto",
+    "-o",
+    `ControlPath=${controlPath}`,
+    // Keep the master alive across brief idle gaps (the connection manager
+    // caches the executor for ~5 min); dispose() tears it down explicitly.
+    "-o",
+    "ControlPersist=300"
+  ];
+  if (config.sshJumpHost?.trim()) {
+    args.push("-J", config.sshJumpHost.trim());
+  }
+  if (config.sshArgs?.trim()) {
+    for (const token of config.sshArgs.trim().split(/\s+/)) {
+      if (token) args.push(token);
+    }
+  }
+  return args;
+}
+function sshTarget(config) {
+  return `${config.username ?? "root"}@${config.host}`;
+}
+function sshChildEnv(config) {
+  const env = { ...process.env };
+  if (config.sshAgent) {
+    env.SSH_AUTH_SOCK = config.sshAgent;
+  }
+  return env;
+}
+
+// ../../packages/adapters/src/system/reverse-tunnel.ts
+import { execFile } from "child_process";
+import { createServer } from "net";
+import { promisify } from "util";
+var execFileAsync = promisify(execFile);
+async function openSystemSshReverseTunnel(opts) {
+  const server = createServer((socket) => opts.onConnection(socket));
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      server.removeListener("error", reject);
+      resolve();
+    });
+  });
+  const localPort = server.address().port;
+  const closeServer = () => new Promise((resolve) => server.close(() => resolve()));
+  const sshBin = opts.sshBin ?? "ssh";
+  const forwardSpec = (remote) => `127.0.0.1:${remote}:127.0.0.1:${localPort}`;
+  let remotePort;
+  try {
+    const { stdout } = await execFileAsync(
+      sshBin,
+      [...opts.baseArgs, "-O", "forward", "-R", forwardSpec(0), opts.target],
+      { env: opts.env }
+    );
+    remotePort = Number.parseInt(stdout.trim(), 10);
+    if (!Number.isInteger(remotePort) || remotePort <= 0) {
+      throw new Error(`ssh -O forward returned no port (stdout: ${JSON.stringify(stdout.trim())})`);
+    }
+  } catch (err) {
+    await closeServer();
+    throw err;
+  }
+  let closed = false;
+  const close = async () => {
+    if (closed) return;
+    closed = true;
+    await execFileAsync(
+      sshBin,
+      [...opts.baseArgs, "-O", "cancel", "-R", forwardSpec(remotePort), opts.target],
+      { env: opts.env }
+    ).catch(() => {
+    });
+    await closeServer();
+  };
+  return { port: remotePort, close };
+}
+
+// ../../packages/adapters/src/system/system-ssh-executor.ts
+var execFileAsync2 = promisify2(execFile2);
+function clampWindow2(value, fallback, min, max) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  return Math.max(min, Math.min(max, Math.floor(value)));
+}
+function describeSshFailure(stderr, fallback) {
+  const text = stderr.trim() || fallback;
+  if (/permission denied|authentication failed|too many authentication failures/i.test(text)) {
+    return new Error(`All configured authentication methods failed: ${text}`);
+  }
+  return new Error(text);
+}
+var SystemSshExecutor = class _SystemSshExecutor {
+  config;
+  controlPath = makeControlPath();
+  /** Resolves once the ControlMaster connection is established. */
+  masterPromise = null;
+  /** Remote-socket → local-forward-socket, one StreamLocal forward per target. */
+  socketForwards = /* @__PURE__ */ new Map();
+  localSockets = /* @__PURE__ */ new Set();
+  disconnectListeners = /* @__PURE__ */ new Set();
+  disposed = false;
+  /** Prefix applied to every remote command - keeps dpkg non-interactive. */
+  static ENV_PREFIX = "export DEBIAN_FRONTEND=noninteractive DPKG_FORCE=confnew && ";
+  constructor(config) {
+    if (!config.host) {
+      throw new Error("System SSH executor requires a host.");
+    }
+    this.config = config;
+  }
+  baseArgs() {
+    return buildBaseSshArgs(this.config, this.controlPath);
+  }
+  onDisconnect(cb) {
+    this.disconnectListeners.add(cb);
+    return () => {
+      this.disconnectListeners.delete(cb);
+    };
+  }
+  /**
+   * On an SSH-level failure (exit 255 — which OpenSSH uses for ANY ssh-level
+   * error: a dropped transport AND an auth failure alike, with no granular
+   * code to tell them apart), authoritatively probe the ControlMaster with
+   * `ssh -O check` instead of guessing from locale/version-dependent stderr.
+   * Only a genuinely-dead master counts as a disconnect: we null it so the
+   * next op reopens, and notify subscribers so the manager can react.
+   */
+  async maybeSignalDisconnect(code) {
+    if (code !== 255 || this.disposed) return;
+    if (!this.masterPromise) return;
+    if (await this.isMasterAlive()) return;
+    this.masterPromise = null;
+    const err = new SshDisconnectedError("SSH master connection lost");
+    for (const cb of [...this.disconnectListeners]) {
+      try {
+        cb(err);
+      } catch {
+      }
+    }
+  }
+  /** Authoritative ControlMaster liveness check: `ssh -O check` exits 0
+   *  ("Master running") when the multiplex socket is alive, non-zero when it's
+   *  missing/dead. Immune to stderr locale/version drift. */
+  async isMasterAlive() {
+    try {
+      await execFileAsync2("ssh", [...this.baseArgs(), "-O", "check", sshTarget(this.config)], {
+        timeout: 5e3,
+        env: sshChildEnv(this.config)
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /** Open (once) the multiplexed master connection. Authenticates here. */
+  async ensureMaster() {
+    if (this.masterPromise) return this.masterPromise;
+    this.masterPromise = (async () => {
+      try {
+        await execFileAsync2("ssh", [...this.baseArgs(), "-fN", sshTarget(this.config)], {
+          timeout: 3e4,
+          env: sshChildEnv(this.config)
+        });
+      } catch (err) {
+        this.masterPromise = null;
+        const e = err;
+        throw describeSshFailure(e.stderr ?? "", safeErrorMessage(err));
+      }
+    })();
+    return this.masterPromise;
+  }
+  /**
+   * Open a reverse tunnel over the ControlMaster: the remote binds an ephemeral
+   * 127.0.0.1 port whose connections arrive here as duplex streams. The
+   * system-ssh counterpart to `SshExecutor.reverseForward` (ssh2) — same shape,
+   * so `CommandExecutor.reverseForward` consumers (the git-credential relay,
+   * future callers) work over agent auth too. Delegates to the generic
+   * `openSystemSshReverseTunnel`.
+   */
+  async reverseForward(onConnection) {
+    await this.ensureMaster();
+    return openSystemSshReverseTunnel({
+      baseArgs: this.baseArgs(),
+      target: sshTarget(this.config),
+      env: sshChildEnv(this.config),
+      onConnection
+    });
+  }
+  /** Run a remote command, resolving with stdout/stderr/exit code (never rejects on non-zero). */
+  async runSsh(remoteCommand, opts) {
+    await this.ensureMaster();
+    return new Promise((resolve, reject) => {
+      const child = spawn2("ssh", [...this.baseArgs(), sshTarget(this.config), remoteCommand], {
+        env: sshChildEnv(this.config),
+        stdio: ["pipe", "pipe", "pipe"]
+      });
+      let stdout = "";
+      let stderr = "";
+      let timedOut = false;
+      let timer = null;
+      if (opts?.timeout) {
+        timer = setTimeout(() => {
+          timedOut = true;
+          child.kill("SIGKILL");
+        }, opts.timeout);
+        timer.unref?.();
+      }
+      child.stdout.on("data", (d) => {
+        stdout += d.toString();
+      });
+      child.stderr.on("data", (d) => {
+        stderr += d.toString();
+      });
+      child.on("error", (e) => {
+        if (timer) clearTimeout(timer);
+        reject(new Error(`ssh failed to start: ${e.message}`));
+      });
+      child.on("close", (code) => {
+        if (timer) clearTimeout(timer);
+        const c = code ?? 1;
+        void this.maybeSignalDisconnect(c).catch(() => {
+        });
+        resolve({ stdout, stderr, code: c, timedOut });
+      });
+      if (opts?.input !== void 0) {
+        child.stdin.write(opts.input);
+      }
+      child.stdin.end();
+    });
+  }
+  async exec(command, opts) {
+    const timeout = opts?.timeout ?? 3e4;
+    const res = await this.runSsh(_SystemSshExecutor.ENV_PREFIX + command, { timeout });
+    if (res.timedOut) {
+      throw new Error(`Command timed out after ${timeout}ms: ${command}`);
+    }
+    if (res.code !== 0) {
+      if (res.code === 255) throw describeSshFailure(res.stderr, `Exit code ${res.code}`);
+      throw new Error(res.stderr.trim() || `Exit code ${res.code}`);
+    }
+    return res.stdout.trim();
+  }
+  async streamExec(command, onLog) {
+    await this.ensureMaster();
+    return new Promise((resolve) => {
+      const child = spawn2(
+        "ssh",
+        [...this.baseArgs(), sshTarget(this.config), _SystemSshExecutor.ENV_PREFIX + command],
+        { env: sshChildEnv(this.config), stdio: ["ignore", "pipe", "pipe"] }
+      );
+      const chunks = [];
+      const onChunk = (chunk, level) => {
+        const text = chunk.toString();
+        if (!text) return;
+        chunks.push(text);
+        onLog(logEntry(text, level, chunk.toString("base64")));
+      };
+      child.stdout.on("data", (chunk) => onChunk(chunk, "info"));
+      child.stderr.on("data", (chunk) => onChunk(chunk, "warn"));
+      child.on("error", (err) => {
+        onLog(logEntry(`Process error: ${err.message}`, "error"));
+        resolve({ code: 1, output: err.message });
+      });
+      child.on("close", (code) => {
+        const c = code ?? 1;
+        void this.maybeSignalDisconnect(c).catch(() => {
+        });
+        resolve({ code: c, output: chunks.join("") });
+      });
+    });
+  }
+  async writeFile(path, content) {
+    const remoteCommand = `mkdir -p ${sq(dirname2(path))} && cat > ${sq(path)}`;
+    const res = await this.runSsh(remoteCommand, { input: content });
+    if (res.code !== 0) {
+      throw new Error(res.stderr.trim() || `Failed to write ${path} (exit ${res.code})`);
+    }
+  }
+  async readFile(path) {
+    const res = await this.runSsh(`cat ${sq(path)}`);
+    if (res.code !== 0) {
+      throw new Error(res.stderr.trim() || `Failed to read ${path} (exit ${res.code})`);
+    }
+    return res.stdout;
+  }
+  async exists(path) {
+    const res = await this.runSsh(`test -e ${sq(path)}`);
+    return res.code === 0;
+  }
+  async mkdir(path) {
+    await this.exec(`mkdir -p ${sq(path)}`);
+  }
+  async rm(path) {
+    try {
+      await this.exec(`rm -rf ${sq(path)}`);
+    } catch {
+    }
+  }
+  /** Pipe a local command's stdout into a remote command's stdin over ssh. */
+  async pipeLocal(localCmd, remoteCmd, onLog, onBytes) {
+    await this.ensureMaster();
+    return new Promise((resolve, reject) => {
+      onLog?.(logEntry(`local: ${localCmd}`));
+      const remote = spawn2("ssh", [...this.baseArgs(), sshTarget(this.config), remoteCmd], {
+        env: sshChildEnv(this.config),
+        stdio: ["pipe", "pipe", "pipe"]
+      });
+      const local = spawn2("sh", ["-c", localCmd], { stdio: ["ignore", "pipe", "pipe"] });
+      if (onBytes) {
+        local.stdout.on("data", (chunk) => onBytes(chunk.length));
+      }
+      local.stdout.pipe(remote.stdin);
+      local.stderr.on("data", (d) => {
+        const text = d.toString().trim();
+        if (text) onLog?.(logEntry(`local stderr: ${text}`, "warn"));
+      });
+      remote.stderr.on("data", (d) => {
+        const text = d.toString().trim();
+        if (text) onLog?.(logEntry(`remote stderr: ${text}`, "warn"));
+      });
+      local.on("error", (e) => reject(new Error(`Local process failed to start: ${e.message}`)));
+      remote.on("error", (e) => reject(new Error(`ssh failed to start: ${e.message}`)));
+      remote.on("close", (code) => resolve({ code: code ?? 1 }));
+    });
+  }
+  async transferIn(localPath, remotePath, onLog, options) {
+    const deps = { config: this.config, hasRemoteCommand: (c) => this.hasRemoteCommand(c) };
+    const excludes = options?.excludes ?? [...TRANSFER_EXCLUDES];
+    const { args: tarArgs, cleanup: cleanupTarList } = await prepareSourceTarArgs(localPath, {
+      excludes,
+      includes: options?.includes,
+      alsoInclude: options?.alsoInclude
+    });
+    const tmpLocalDir = await mkdtemp3(join3(tmpdir3(), "openship-xfer-"));
+    const localArchive = join3(tmpLocalDir, "context.tar.gz");
+    const remoteArchive = `${remotePath}.openship-xfer.tar.gz`;
+    try {
+      onLog?.(logEntry("Packing source into a single archive..."));
+      await packLocalArchive(tarArgs, localArchive);
+      const totalBytes = (await stat2(localArchive)).size;
+      await this.exec(`mkdir -p ${sq(dirname2(remoteArchive))}`);
+      const rsync = await canUseRemoteRsync(deps);
+      if (rsync.ok) {
+        onLog?.(logEntry(`Uploading ${formatBytes(totalBytes)} archive via rsync (resumable)...`));
+        await uploadFileWithRsync(localArchive, remoteArchive, deps, onLog);
+      } else {
+        onLog?.(
+          logEntry(`Uploading ${formatBytes(totalBytes)} archive over the SSH connection \u2014 ${rsync.reason}.`)
+        );
+        await this.streamArchiveWithRetry(localArchive, remoteArchive, onLog);
+      }
+      await extractRemoteArchive((command) => this.exec(command), remoteArchive, remotePath, totalBytes, onLog);
+    } finally {
+      await cleanupTarList().catch(() => {
+      });
+      await fsRm3(tmpLocalDir, { recursive: true, force: true }).catch(() => {
+      });
+    }
+  }
+  /** Stream a single local file over the ControlMaster, retrying from 0 on
+   *  failure (the `cat >` truncates, so there is no partial to resume). */
+  async streamArchiveWithRetry(localArchive, remoteArchive, onLog) {
+    const MAX_ATTEMPTS = 3;
+    let lastErr = null;
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+      if (attempt > 1) onLog?.(logEntry(`Retrying upload (attempt ${attempt}/${MAX_ATTEMPTS})...`, "warn"));
+      try {
+        const { code } = await this.pipeLocal(`cat ${sq(localArchive)}`, `cat > ${sq(remoteArchive)}`, onLog);
+        if (code === 0) return;
+        lastErr = new Error(`archive upload failed (exit ${code})`);
+      } catch (err) {
+        lastErr = err instanceof Error ? err : new Error(String(err));
+      }
+    }
+    throw lastErr ?? new Error("archive upload failed");
+  }
+  async hasRemoteCommand(command) {
+    try {
+      const out = await this.exec(`command -v ${command} >/dev/null 2>&1 && echo ok`, { timeout: 5e3 });
+      return out.trim() === "ok";
+    } catch {
+      return false;
+    }
+  }
+  async forwardPort(remoteHost, remotePort) {
+    await this.ensureMaster();
+    const child = spawn2(
+      "ssh",
+      [...this.baseArgs(), "-W", `${remoteHost}:${remotePort}`, sshTarget(this.config)],
+      { env: sshChildEnv(this.config), stdio: ["pipe", "pipe", "ignore"] }
+    );
+    const duplex = Duplex.from({ writable: child.stdin, readable: child.stdout });
+    duplex.on("close", () => {
+      try {
+        child.kill();
+      } catch {
+      }
+    });
+    child.on("exit", () => {
+      duplex.destroy();
+    });
+    child.on("error", (e) => {
+      duplex.destroy(e);
+    });
+    return duplex;
+  }
+  /** Ensure a StreamLocal forward (local unix socket → remote socket) on the master. */
+  async ensureSocketForward(remoteSocket) {
+    let pending = this.socketForwards.get(remoteSocket);
+    if (!pending) {
+      pending = (async () => {
+        await this.ensureMaster();
+        const localSocket = `/tmp/openship-fwd-${process.pid}-${randomBytes2(6).toString("hex")}.sock`;
+        await execFileAsync2(
+          "ssh",
+          [...this.baseArgs(), "-O", "forward", "-L", `${localSocket}:${remoteSocket}`, sshTarget(this.config)],
+          { timeout: 15e3, env: sshChildEnv(this.config) }
+        );
+        this.localSockets.add(localSocket);
+        return localSocket;
+      })();
+      pending.catch(() => {
+        if (this.socketForwards.get(remoteSocket) === pending) {
+          this.socketForwards.delete(remoteSocket);
+        }
+      });
+      this.socketForwards.set(remoteSocket, pending);
+    }
+    return pending;
+  }
+  async forwardUnixSocket(socketPath) {
+    const attempt = async () => {
+      const localSocket = await this.ensureSocketForward(socketPath);
+      const sock = netConnect(localSocket);
+      await once(sock, "connect");
+      return sock;
+    };
+    try {
+      return await attempt();
+    } catch {
+      this.socketForwards.delete(socketPath);
+      return attempt();
+    }
+  }
+  /**
+   * Run a best-effort, fire-and-forget control command on the remote over the
+   * existing master (no output captured, errors swallowed). Used for PTY
+   * resize and marker cleanup.
+   */
+  fireAndForget(command) {
+    try {
+      spawn2("ssh", [...this.baseArgs(), sshTarget(this.config), command], {
+        env: sshChildEnv(this.config),
+        stdio: "ignore"
+      }).on("error", () => {
+      });
+    } catch {
+    }
+  }
+  async openShell(opts) {
+    await this.ensureMaster();
+    const cols = clampWindow2(opts?.cols, 80, 1, 1e3);
+    const rows = clampWindow2(opts?.rows, 24, 1, 500);
+    const term = opts?.term || "xterm-256color";
+    const ptyMarker = `/tmp/openship-pty-${process.pid}-${randomBytes2(6).toString("hex")}`;
+    const remoteInit = `tty > ${ptyMarker} 2>/dev/null; stty sane 2>/dev/null; stty cols ${cols} rows ${rows} 2>/dev/null; exec "\${SHELL:-/bin/sh}" -l`;
+    const env = { ...sshChildEnv(this.config), TERM: term };
+    const child = spawn2("ssh", [...this.baseArgs(), "-tt", sshTarget(this.config), remoteInit], {
+      env,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    child.stdin.on("error", () => {
+    });
+    child.stdout.on("error", () => {
+    });
+    child.stderr.on("error", () => {
+    });
+    const closeListeners = [];
+    let closed = false;
+    let resizeTimer = null;
+    let pendingSize = null;
+    const fireClose = (code, signal) => {
+      if (closed) return;
+      closed = true;
+      if (resizeTimer) clearTimeout(resizeTimer);
+      this.fireAndForget(`rm -f ${ptyMarker}`);
+      for (const cb of closeListeners) {
+        try {
+          cb(code, signal);
+        } catch {
+        }
+      }
+    };
+    child.on("exit", (code, signal) => fireClose(code, signal ?? void 0));
+    child.on("error", () => fireClose(null));
+    return {
+      stdin: child.stdin,
+      stdout: child.stdout,
+      stderr: child.stderr,
+      setWindow: (c, r) => {
+        pendingSize = { c: clampWindow2(c, 80, 1, 1e3), r: clampWindow2(r, 24, 1, 500) };
+        if (resizeTimer) clearTimeout(resizeTimer);
+        resizeTimer = setTimeout(() => {
+          const size = pendingSize;
+          pendingSize = null;
+          if (!size || closed) return;
+          this.fireAndForget(
+            `for i in 1 2 3 4 5 6; do P=$(cat ${ptyMarker} 2>/dev/null); if [ -n "$P" ]; then stty -F "$P" cols ${size.c} rows ${size.r} 2>/dev/null || stty -f "$P" cols ${size.c} rows ${size.r} 2>/dev/null; break; fi; sleep 0.2; done`
+          );
+        }, 60);
+        resizeTimer.unref?.();
+      },
+      close: (_signal) => {
+        if (resizeTimer) clearTimeout(resizeTimer);
+        try {
+          child.kill();
+        } catch {
+        }
+      },
+      onClose: (cb) => {
+        closeListeners.push(cb);
+      }
+    };
+  }
+  async dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    if (this.masterPromise) {
+      try {
+        await execFileAsync2("ssh", [...this.baseArgs(), "-O", "exit", sshTarget(this.config)], {
+          timeout: 5e3,
+          env: sshChildEnv(this.config)
+        });
+      } catch {
+      }
+    }
+    this.masterPromise = null;
+    this.socketForwards.clear();
+    for (const socket of this.localSockets) {
+      await unlink(socket).catch(() => {
+      });
+    }
+    this.localSockets.clear();
+  }
+};
+
+// ../../packages/adapters/src/system/executor.ts
+function createExecutor(ssh) {
+  if (ssh) {
+    if (ssh.useSystemSsh) return new SystemSshExecutor(ssh);
+    return new SshExecutor(ssh);
+  }
+  return new LocalExecutor();
+}
+function hostControlDisabled() {
+  return process.env.OPENSHIP_HOST_CONTROL?.trim().toLowerCase() === "false";
+}
+function createHostExecutor() {
+  if (hostControlDisabled()) {
+    throw new Error(
+      "Host control is disabled on this instance (OPENSHIP_HOST_CONTROL=false). Re-run `openship up` without --no-host-control to allow host operations."
+    );
+  }
+  const host = process.env.OPENSHIP_HOST_SSH_HOST?.trim();
+  if (!host) return new LocalExecutor();
+  const keyPath = process.env.OPENSHIP_HOST_SSH_KEY?.trim();
+  const portRaw = Number(process.env.OPENSHIP_HOST_SSH_PORT || "22");
+  const port = Number.isInteger(portRaw) && portRaw > 0 && portRaw < 65536 ? portRaw : 22;
+  let privateKey;
+  if (keyPath) {
+    try {
+      privateKey = readFileSync(keyPath, "utf8");
+    } catch (err) {
+      throw new Error(
+        `Cannot read host SSH key at OPENSHIP_HOST_SSH_KEY=${keyPath}: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+  return new SshExecutor({
+    host,
+    port,
+    username: process.env.OPENSHIP_HOST_SSH_USER?.trim() || "root",
+    privateKey
+  });
+}
+
+export {
+  SshExecutor,
+  SystemSshExecutor,
+  createExecutor,
+  hostControlDisabled,
+  createHostExecutor
+};