openship 0.6.1 → 0.6.6

package/dist/{chunk-VDDMADOF.js → chunk-LH2PLRQO.js}

@@ -5,12 +5,12 @@ const require = __ospCreateRequire(import.meta.url);
 import {
   getTarCreateEnv,
   prepareSourceTarArgs
-} from "./chunk-6ODUBKUB.js";
+} from "./chunk-Q7WGTQQ5.js";
 import {
   TRANSFER_EXCLUDES,
   packageManagerEnsureCommand,
   safeErrorMessage
-} from "./chunk-OTLSJYAC.js";
+} from "./chunk-UJ6JZM65.js";
 
 // ../../packages/adapters/src/runtime/git-clone.ts
 function sq(value) {
@@ -193,6 +193,19 @@ var BuildCancelledError = class extends Error {
     this.name = "BuildCancelledError";
   }
 };
+async function killProcessesUnderDir(executor, dir, opts) {
+  const quoted = sq(dir);
+  const roots = opts?.includeSuffixed ? [quoted, `${quoted}-*`] : [quoted];
+  const patterns = roots.flatMap((root) => [
+    root,
+    `${root}/*`,
+    `${root}" (deleted)"`,
+    `${root}/*" (deleted)"`
+  ]);
+  const scan = (sig) => `for p in /proc/[0-9]*; do c=$(readlink "$p/cwd" 2>/dev/null); case "$c" in ${patterns.join("|")}) kill -${sig} "\${p##*/}" 2>/dev/null || true;; esac; done`;
+  await executor.exec(`${scan("TERM")}; sleep 2; ${scan("KILL")}`).catch(() => {
+  });
+}
 async function runBuildPipeline(env, config, logger) {
   let startTime = Date.now();
   let currentStep = "prepare";
@@ -413,6 +426,7 @@ export {
   localGitSshWriter,
   BuildLogger,
   BuildCancelledError,
+  killProcessesUnderDir,
   runBuildPipeline,
   parseLogLevel,
   detectBuildKillHint,

package/dist/{chunk-EMXI4UCU.js → chunk-LUKYPVJ4.js}

@@ -7,14 +7,14 @@ import {
   localGitSshWriter,
   materializeGitSsh,
   sq
-} from "./chunk-VDDMADOF.js";
+} from "./chunk-LH2PLRQO.js";
 import {
   getTarCreateEnv,
   prepareSourceTarArgs
-} from "./chunk-6ODUBKUB.js";
+} from "./chunk-Q7WGTQQ5.js";
 import {
   packageManagerEnsureCommand
-} from "./chunk-OTLSJYAC.js";
+} from "./chunk-UJ6JZM65.js";
 import {
   __commonJS,
   __toESM
@@ -480,16 +480,34 @@ var require_ignore = __commonJS({
 
 // ../../packages/adapters/src/runtime/docker-paths.ts
 import { access, readdir } from "fs/promises";
-import { isAbsolute, join, relative, sep } from "path";
+import { isAbsolute, join, relative, resolve, sep } from "path";
 function toPosixPath(value) {
   return value.split(sep).filter(Boolean).join("/");
 }
+function toSafeSegments(value, label) {
+  const segments = value.split(/[\\/]/).filter((segment) => segment && segment !== ".");
+  if (segments.includes("..")) {
+    throw new Error(
+      `Invalid ${label} ${JSON.stringify(value)}: path segments must not contain "..".`
+    );
+  }
+  return segments;
+}
 function normalizeDockerRelativePath(value) {
   const normalized = value?.trim().replace(/^\.\//, "").replace(/^\/+|\/+$/g, "");
   if (!normalized || normalized === ".") {
     return "";
   }
-  return normalized.split(/[\\/]/).filter(Boolean).join("/");
+  return toSafeSegments(normalized, "path").join("/");
+}
+function resolveWithinDirectory(baseDir, relativePath) {
+  const base = resolve(baseDir);
+  const target = resolve(base, ...toSafeSegments(relativePath?.trim() ?? "", "path"));
+  const escape = relative(base, target);
+  if (escape === ".." || escape.startsWith(`..${sep}`) || isAbsolute(escape)) {
+    throw new Error(`Resolved path ${JSON.stringify(target)} escapes ${JSON.stringify(base)}.`);
+  }
+  return target;
 }
 function normalizeDockerRootDirectory(rootDirectory, localPath) {
   let normalized = rootDirectory?.trim() ?? "";
@@ -509,7 +527,7 @@ function normalizeDockerRootDirectory(rootDirectory, localPath) {
   if (!normalized || normalized === ".") {
     return "";
   }
-  return toPosixPath(normalized);
+  return toSafeSegments(normalized, "rootDirectory").join("/");
 }
 function resolveExplicitDockerfileCandidate(rootDirectory, dockerfilePath) {
   const normalizedRootDirectory = normalizeDockerRelativePath(rootDirectory);
@@ -904,7 +922,7 @@ import { join as join2, relative as relative2, sep as sep2 } from "path";
 var GIT_CLONE_IDLE_TIMEOUT_MS = 5 * 6e4;
 var GIT_CHECKOUT_IDLE_TIMEOUT_MS = 6e4;
 function spawnGit(args, opts) {
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve2, reject) => {
     const child = spawn("git", args, {
       stdio: ["ignore", "pipe", "pipe"],
       env: {
@@ -954,7 +972,7 @@ function spawnGit(args, opts) {
     });
     child.on("close", (code) => {
       clearTimeout(idleTimer);
-      if (code === 0) resolve();
+      if (code === 0) resolve2();
       else reject(new Error(`git exited with code ${code}: ${stderr.trim().slice(-500) || "no stderr"}`));
     });
   });
@@ -1014,7 +1032,7 @@ async function applyDockerignore(contextDir, config) {
 async function materializeLocalSource(sourcePath, targetPath) {
   const { args, cleanup } = await prepareSourceTarArgs(sourcePath);
   try {
-    await new Promise((resolve, reject) => {
+    await new Promise((resolve2, reject) => {
       const create = spawn("tar", args, { env: getTarCreateEnv() });
       const extract = spawn("tar", ["-xzf", "-", "-C", targetPath]);
       let err = "";
@@ -1027,7 +1045,7 @@ async function materializeLocalSource(sourcePath, targetPath) {
       create.on("close", (code) => createCode = code);
       create.stdout.pipe(extract.stdin);
       extract.on("close", (code) => {
-        if (code === 0 && (createCode ?? 0) === 0) return resolve();
+        if (code === 0 && (createCode ?? 0) === 0) return resolve2();
         const parts = [
           createCode ? `pack exited ${createCode}: ${createErr.trim().slice(-500)}` : "",
           code ? `extract exited ${code}: ${err.trim().slice(-500)}` : ""
@@ -1173,6 +1191,7 @@ async function createDockerBuildContext(config, opts) {
 
 export {
   normalizeDockerRelativePath,
+  resolveWithinDirectory,
   resolveDockerfileCandidates,
   staticBuilderOutputPath,
   generateDockerfile,

package/dist/{chunk-UC7YIEHT.js → chunk-MLYSEZQB.js}

@@ -3,16 +3,16 @@
 import { createRequire as __ospCreateRequire } from "node:module";
 const require = __ospCreateRequire(import.meta.url);
 import {
-  connectSshClient,
   getTarCreateEnv,
+  prepareSourceTarArgs
+} from "./chunk-Q7WGTQQ5.js";
+import {
+  connectSshClient,
+  openDockerDialStdioChannel,
   openSftp,
   openSshUnixSocket,
-  prepareSourceTarArgs,
   reconcileKnownHosts
-} from "./chunk-6ODUBKUB.js";
-import {
-  SshDisconnectedError
-} from "./chunk-ZCFVHA25.js";
+} from "./chunk-PCPVTH6M.js";
 import {
   LocalExecutor
 } from "./chunk-6FH4AXVY.js";
@@ -24,13 +24,80 @@ import {
   sq
 } from "./chunk-ZFJXPCQP.js";
 import {
+  HOST_CHANNEL_AUTH_REJECTED,
+  HOST_CHANNEL_NOT_PROVISIONED,
+  HOST_CHANNEL_UNPROVISIONED,
+  HostChannelUnavailableError,
+  SshDisconnectedError,
   TRANSFER_EXCLUDES,
+  commandForError,
+  explainHostChannelCause,
   formatBytes,
+  hostChannelAccount,
+  hostFirewallRule,
+  isSshAuthError,
   safeErrorMessage
-} from "./chunk-OTLSJYAC.js";
+} from "./chunk-UJ6JZM65.js";
 
 // ../../packages/adapters/src/system/executor.ts
 import { existsSync, readFileSync } from "fs";
+import { networkInterfaces } from "os";
+
+// ../../packages/adapters/src/system/reachability.ts
+import { connect } from "net";
+import { request } from "http";
+function classifyDialError(code) {
+  switch (code) {
+    case "ECONNREFUSED":
+    case "ECONNRESET":
+      return "refused";
+    case "ENOTFOUND":
+    case "EAI_AGAIN":
+      return "unresolved";
+    case "EHOSTUNREACH":
+    case "ENETUNREACH":
+    case "ENETDOWN":
+      return "no_route";
+    // The kernel's own connect timeout, i.e. our `timeout` reported for us.
+    case "ETIMEDOUT":
+      return "timeout";
+    default:
+      return "error";
+  }
+}
+function probeTcpDetailed(host, port, timeoutMs = 2500) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (result, socket2) => {
+      if (settled) return;
+      settled = true;
+      try {
+        socket2?.destroy();
+      } catch {
+      }
+      resolve(result);
+    };
+    const socket = connect({ host, port });
+    socket.setTimeout(timeoutMs);
+    socket.once("connect", () => done({ ok: true }, socket));
+    socket.once(
+      "timeout",
+      () => done({ ok: false, reason: "timeout", message: `no response within ${timeoutMs}ms` }, socket)
+    );
+    socket.once("error", (err) => {
+      const errno = err;
+      done(
+        {
+          ok: false,
+          reason: classifyDialError(errno.code),
+          ...errno.code ? { code: errno.code } : {},
+          ...errno.message ? { message: errno.message } : {}
+        },
+        socket
+      );
+    });
+  });
+}
 
 // ../../packages/adapters/src/system/ssh-executor.ts
 import { createReadStream } from "fs";
@@ -240,7 +307,7 @@ var SshExecutor = class _SshExecutor {
   async connect() {
     if (this.client) return this.client;
     if (this.connecting) return this.connecting;
-    this.connecting = (async () => {
+    const attempt = (async () => {
       const client = await connectSshClient(this.config);
       const onTransportDown = (cause) => {
         if (this.client !== client) return;
@@ -252,10 +319,14 @@ var SshExecutor = class _SshExecutor {
       client.on("end", () => onTransportDown());
       client.on("error", (err) => onTransportDown(err));
       this.client = client;
-      this.connecting = null;
       return client;
     })();
-    return this.connecting;
+    this.connecting = attempt;
+    const clearMemo = () => {
+      if (this.connecting === attempt) this.connecting = null;
+    };
+    attempt.then(clearMemo, clearMemo);
+    return attempt;
   }
   /**
    * Subscribe to transport-level disconnects. Returns an unsubscribe fn.
@@ -402,7 +473,9 @@ var SshExecutor = class _SshExecutor {
       };
       this.inflight.add(abort);
       timer = setTimeout(
-        () => finish(() => reject(new Error(`Command timed out after ${timeout}ms: ${command}`))),
+        () => finish(
+          () => reject(new Error(`Command timed out after ${timeout}ms: ${commandForError(command)}`))
+        ),
         timeout
       );
       client.exec(_SshExecutor.ENV_PREFIX + command, (err, stream) => {
@@ -706,24 +779,23 @@ var SshExecutor = class _SshExecutor {
    * 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).
+   * forwarding.
+   *
+   * Deliberately WITHOUT `ENV_PREFIX`: that prefix only exports apt's
+   * non-interactive variables (it sets no PATH, despite what the comment here
+   * used to claim), and the bridge's own ephemeral dial-stdio client opens the
+   * bare command. Two dial-stdio channels that differ by a shell prefix are two
+   * transports, and the bridge picks one by probing the other.
+   *
+   * Failure diagnostics (daemon down, socket permission, `docker: command not
+   * found`, an sshd ForceCommand banner) ride ON the returned channel — see
+   * `attachDialStdioDiagnostics`. They used to go to `console.warn` while the
+   * caller got a bare socket reset, which is how a host with no running dockerd
+   * reported itself as `socket hang up`.
    */
   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);
-      });
-    });
+    return openDockerDialStdioChannel(client);
   }
   async forwardPort(remoteHost, remotePort) {
     const client = await this.connect();
@@ -1200,7 +1272,7 @@ var SystemSshExecutor = class _SystemSshExecutor {
     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}`);
+      throw new Error(`Command timed out after ${timeout}ms: ${commandForError(command)}`);
     }
     if (res.code !== 0) {
       if (res.code === 255) throw describeSshFailure(res.stderr, `Exit code ${res.code}`);
@@ -1208,14 +1280,22 @@ var SystemSshExecutor = class _SystemSshExecutor {
     }
     return res.stdout.trim();
   }
-  async streamExec(command, onLog) {
+  async streamExec(command, onLog, opts) {
     await this.ensureMaster();
+    const signal = opts?.signal;
+    if (signal?.aborted) return { code: 0, output: "" };
     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"] }
       );
+      let aborted = false;
+      const onAbort = () => {
+        aborted = true;
+        child.kill("SIGKILL");
+      };
+      signal?.addEventListener("abort", onAbort, { once: true });
       const chunks = [];
       const onChunk = (chunk, level) => {
         const text = chunk.toString();
@@ -1226,11 +1306,13 @@ var SystemSshExecutor = class _SystemSshExecutor {
       child.stdout.on("data", (chunk) => onChunk(chunk, "info"));
       child.stderr.on("data", (chunk) => onChunk(chunk, "warn"));
       child.on("error", (err) => {
+        signal?.removeEventListener("abort", onAbort);
         onLog(logEntry(`Process error: ${err.message}`, "error"));
         resolve({ code: 1, output: err.message });
       });
       child.on("close", (code) => {
-        const c = code ?? 1;
+        signal?.removeEventListener("abort", onAbort);
+        const c = aborted ? 0 : code ?? 1;
         void this.maybeSignalDisconnect(c).catch(() => {
         });
         resolve({ code: c, output: chunks.join("") });
@@ -1524,8 +1606,12 @@ function createExecutor(ssh) {
   }
   return localExecutor;
 }
+var hostControlOverride = null;
+function setHostControlOverride(disabled) {
+  hostControlOverride = disabled;
+}
 function hostControlDisabled() {
-  return process.env.OPENSHIP_HOST_CONTROL?.trim().toLowerCase() === "false";
+  return hostControlOverride ?? process.env.OPENSHIP_HOST_CONTROL?.trim().toLowerCase() === "false";
 }
 function runningInContainer() {
   if (process.env.OPENSHIP_IN_CONTAINER?.trim().toLowerCase() === "true") return true;
@@ -1539,39 +1625,253 @@ function runningInContainer() {
     return false;
   }
 }
+function hostChannelPort() {
+  const raw = Number(process.env.OPENSHIP_HOST_SSH_PORT || "22");
+  return Number.isInteger(raw) && raw > 0 && raw < 65536 ? raw : 22;
+}
+function hostChannelUser() {
+  return hostChannelAccount(process.env);
+}
+function readHostChannelKey(keyPath) {
+  let contents;
+  try {
+    contents = readFileSync(keyPath, "utf8");
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    return { reason: `Cannot read the host SSH key at ${keyPath} (${detail}).` };
+  }
+  if (!contents.trim()) return { reason: `The host SSH key at ${keyPath} is empty.` };
+  return { key: contents };
+}
+function containerBridgeCidr() {
+  for (const addrs of Object.values(networkInterfaces())) {
+    for (const addr of addrs ?? []) {
+      if (addr.family !== "IPv4" || addr.internal) continue;
+      const prefix = Number(addr.cidr?.split("/")[1]);
+      if (!Number.isInteger(prefix) || prefix < 8 || prefix > 32) continue;
+      const octets = addr.address.split(".").map(Number);
+      if (octets.length !== 4 || octets.some((o) => !Number.isInteger(o) || o < 0 || o > 255)) continue;
+      const asInt = (octets[0] << 24 | octets[1] << 16 | octets[2] << 8 | octets[3]) >>> 0;
+      const mask = 4294967295 << 32 - prefix >>> 0;
+      const net = (asInt & mask) >>> 0;
+      return `${net >>> 24 & 255}.${net >>> 16 & 255}.${net >>> 8 & 255}.${net & 255}/${prefix}`;
+    }
+  }
+  return null;
+}
+function probeDetail(probe) {
+  const { code, message } = probe;
+  if (code && message && !message.includes(code)) return `${code}: ${message}`;
+  return code ?? message;
+}
+function explainDialFailure(probe, host, port, target) {
+  const { headline, body, firewallShaped } = explainHostChannelCause(probe.reason, {
+    target,
+    host,
+    detail: probeDetail(probe)
+  });
+  const hint = body ? `${headline}. ${body}` : `${headline}.`;
+  if (!firewallShaped) return { hint };
+  const cidr = containerBridgeCidr();
+  return { hint, rule: hostFirewallRule("unknown", cidr ? [cidr] : [], port) };
+}
+var AUTH_MEMO_OK_MS = 3e4;
+var AUTH_MEMO_FAIL_MS = 5e3;
+var authMemo = null;
+function invalidateHostChannelAuth() {
+  authMemo = null;
+}
+function probeForwarding(client, timeoutMs) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (verdict) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(verdict);
+    };
+    const timer = setTimeout(() => finish("unknown"), timeoutMs);
+    timer.unref?.();
+    try {
+      client.forwardOut("127.0.0.1", 0, "127.0.0.1", 1, (err, stream) => {
+        if (stream) {
+          stream.destroy();
+          finish("ok");
+          return;
+        }
+        const reason = err?.reason;
+        const message = err?.message;
+        if (reason === 1 || reason === 3) return finish("blocked");
+        if (typeof message === "string" && /administratively prohibited/i.test(message)) {
+          return finish("blocked");
+        }
+        finish("ok");
+      });
+    } catch {
+      finish("unknown");
+    }
+  });
+}
+async function verifyHostChannelAuth(config) {
+  const memoKey = `${config.username}@${config.host}:${config.port}#${config.privateKey.length}`;
+  if (authMemo?.key === memoKey && authMemo.expires > Date.now()) {
+    return authMemo.hint ? { hint: authMemo.hint, forwarding: authMemo.forwarding } : { forwarding: authMemo.forwarding };
+  }
+  let hint = null;
+  let forwarding = "unknown";
+  try {
+    const { connectSshClient: connectSshClient2 } = await import("./ssh-client-JBMA7SN4.js");
+    const client = await connectSshClient2({
+      host: config.host,
+      port: config.port,
+      username: config.username,
+      privateKey: config.privateKey,
+      readyTimeoutMs: config.timeoutMs,
+      // Load-bearing: it selects describeSshAuthFailure's host-channel wording, so the
+      // hint an operator reads here is the same sentence the deploy log gives them.
+      hostChannel: true
+    });
+    forwarding = await probeForwarding(
+      client,
+      config.timeoutMs
+    );
+    client.end();
+  } catch (err) {
+    if (isSshAuthError(err)) {
+      hint = err instanceof Error ? err.message : HOST_CHANNEL_AUTH_REJECTED;
+    }
+  }
+  authMemo = {
+    key: memoKey,
+    hint,
+    forwarding,
+    expires: Date.now() + (hint ? AUTH_MEMO_FAIL_MS : AUTH_MEMO_OK_MS)
+  };
+  return hint ? { hint, forwarding } : { forwarding };
+}
+async function hostChannelHealth(timeoutMs = 2500) {
+  if (hostControlDisabled()) {
+    return {
+      ok: false,
+      code: "disabled",
+      hint: "Host control is off (OPENSHIP_HOST_CONTROL=false). Re-run `openship up` without --no-host-control."
+    };
+  }
+  const host = process.env.OPENSHIP_HOST_SSH_HOST?.trim();
+  if (!host) {
+    if (runningInContainer()) {
+      return {
+        ok: false,
+        code: "not_configured",
+        hint: `${HOST_CHANNEL_UNPROVISIONED} ${HOST_CHANNEL_NOT_PROVISIONED}`
+      };
+    }
+    return { ok: true, code: "not_applicable" };
+  }
+  const port = hostChannelPort();
+  const target = `${hostChannelUser()}@${host}:${port}`;
+  const keyPath = process.env.OPENSHIP_HOST_SSH_KEY?.trim();
+  let privateKey;
+  if (keyPath) {
+    const read = readHostChannelKey(keyPath);
+    if (read.reason) {
+      return {
+        ok: false,
+        code: "key_unreadable",
+        host,
+        port,
+        target,
+        hint: `${read.reason} ${HOST_CHANNEL_NOT_PROVISIONED}`
+      };
+    }
+    privateKey = read.key;
+  }
+  const probe = await probeTcpDetailed(host, port, timeoutMs);
+  if (!probe.ok) {
+    return {
+      ok: false,
+      code: "unreachable",
+      host,
+      port,
+      target,
+      cause: probe.reason,
+      ...explainDialFailure(probe, host, port, target)
+    };
+  }
+  let forwarding = "unknown";
+  if (privateKey) {
+    const verdict = await verifyHostChannelAuth({
+      host,
+      port,
+      username: hostChannelUser(),
+      privateKey,
+      timeoutMs
+    });
+    if (verdict.hint) {
+      return { ok: false, code: "auth_rejected", host, port, target, hint: verdict.hint };
+    }
+    forwarding = verdict.forwarding;
+  }
+  return { ok: true, code: "ok", host, port, target, forwarding };
+}
+function unavailableExecutor(reason, code = "not_configured") {
+  const refuse = async () => {
+    throw new HostChannelUnavailableError(code, reason);
+  };
+  return {
+    exec: refuse,
+    streamExec: refuse,
+    writeFile: refuse,
+    readFile: refuse,
+    exists: refuse,
+    mkdir: refuse,
+    rm: refuse,
+    transferIn: refuse,
+    // Nothing was ever opened, so releasing must not be the one call that throws.
+    dispose: async () => {
+    }
+  };
+}
 function createHostExecutor() {
   if (hostControlDisabled()) {
-    throw new Error(
+    throw new HostChannelUnavailableError(
+      "disabled",
       "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) {
     if (runningInContainer()) {
-      throw new Error(
-        "This operation targets the HOST machine, but no host channel is configured (OPENSHIP_HOST_SSH_HOST is unset) and Openship is running in a container \u2014 so it would have run inside the container instead, against the wrong filesystem. Re-run `openship up` to provision the host channel."
+      throw new HostChannelUnavailableError(
+        "not_configured",
+        `This operation targets the HOST machine, but no host channel is configured (OPENSHIP_HOST_SSH_HOST is unset) and Openship is running in a container \u2014 so it would have run inside the container instead, against the wrong filesystem. ${HOST_CHANNEL_NOT_PROVISIONED}`
       );
     }
     return 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)}`
-      );
-    }
+  if (!keyPath) {
+    throw new HostChannelUnavailableError(
+      "not_configured",
+      `A host channel is configured (OPENSHIP_HOST_SSH_HOST) but OPENSHIP_HOST_SSH_KEY is unset, so there is no credential to connect to the host with. ${HOST_CHANNEL_NOT_PROVISIONED}`
+    );
+  }
+  const read = readHostChannelKey(keyPath);
+  if (read.reason) {
+    throw new HostChannelUnavailableError(
+      "not_configured",
+      `${read.reason} ${HOST_CHANNEL_NOT_PROVISIONED}`
+    );
   }
   return new SshExecutor({
     host,
-    port,
-    username: process.env.OPENSHIP_HOST_SSH_USER?.trim() || "root",
-    privateKey
+    port: hostChannelPort(),
+    username: hostChannelUser(),
+    privateKey: read.key,
+    // One hop over the docker bridge: it answers at once or it is being filtered.
+    // 20s of silence per host operation reads as a hang, not as a failure.
+    readyTimeoutMs: 8e3,
+    hostChannel: true
   });
 }
 
@@ -1579,6 +1879,11 @@ export {
   SshExecutor,
   SystemSshExecutor,
   createExecutor,
+  setHostControlOverride,
   hostControlDisabled,
+  containerBridgeCidr,
+  invalidateHostChannelAuth,
+  hostChannelHealth,
+  unavailableExecutor,
   createHostExecutor
 };