openship 0.2.3 → 0.4.0

package/dist/chunk-KD7VO4LG.js

@@ -0,0 +1,2617 @@
+import {
+  createDockerBuildContext,
+  generateDockerfile,
+  prepareSourceTree,
+  resolveDockerfileCandidates,
+  resolveServiceDockerfile
+} from "./chunk-HFYDYK4D.js";
+import {
+  BuildLogger,
+  assembleGitClone,
+  materializeGitSsh,
+  parseLogLevel,
+  shellGitSshWriter,
+  sq,
+  transferLocalDirectory
+} from "./chunk-YL67EWYZ.js";
+import {
+  connectSshClient,
+  execSshCommand,
+  openSshExecChannel,
+  openSshUnixSocket
+} from "./chunk-4MG3BVHE.js";
+import {
+  isRuntimeNotFoundError
+} from "./chunk-4LEL3H2Z.js";
+import {
+  safeErrorMessage,
+  withTimeout
+} from "./chunk-JZLNHGLW.js";
+
+// ../../packages/adapters/src/runtime/docker.ts
+import Dockerode from "dockerode";
+import { PassThrough, Writable } from "stream";
+
+// ../../packages/adapters/src/runtime/source-tarball.ts
+function githubTarballUrl(repoUrl, ref) {
+  if (!repoUrl || !ref) return null;
+  const m = repoUrl.match(/^https:\/\/github\.com\/([^/]+)\/(.+?)(?:\.git)?\/?$/i);
+  if (!m) return null;
+  const [, owner, repo] = m;
+  if (!owner || !repo) return null;
+  return `https://api.github.com/repos/${owner}/${repo}/tarball/${ref}`;
+}
+async function downloadTarballOnRemote(executor, opts) {
+  const dest = sq(opts.destDir);
+  const tmp = sq(`${opts.destDir}.opsh-src.tar.gz`);
+  const authExport = opts.token ? `export OPSH_GH_TOK=${sq(opts.token)}; ` : "";
+  const authHeader = opts.token ? `-H "Authorization: Bearer $OPSH_GH_TOK" ` : "";
+  const cmd = `rm -rf ${dest} ${tmp} && mkdir -p ${dest} && ${authExport}curl -fSL --retry 3 --retry-delay 2 ${authHeader}-o ${tmp} ${sq(opts.url)} && tar -xzf ${tmp} --strip-components=1 -C ${dest} && rm -f ${tmp}`;
+  const { code } = await executor.streamExec(cmd, (entry) => opts.onLog?.(entry));
+  if (code !== 0) {
+    throw new Error(`tarball download exited with code ${code}`);
+  }
+}
+
+// ../../packages/adapters/src/runtime/volume-namespace.ts
+var MODE_SUFFIX = /:(ro|rw|z|Z|nocopy)$/;
+function scopedVolumeName(slug, name) {
+  return `openship-${slug}-${name}`;
+}
+function isHostPathSource(source) {
+  return source.startsWith("/") || source.startsWith("./") || source.startsWith("../") || source.startsWith("~");
+}
+function scopeVolumeBinds(slug, rawVolumes, enabled) {
+  if (!enabled) return rawVolumes;
+  const prefix = `openship-${slug}-`;
+  return rawVolumes.map((spec) => {
+    const modeMatch = spec.match(MODE_SUFFIX);
+    const mode = modeMatch ? modeMatch[0] : "";
+    const body = mode ? spec.slice(0, -mode.length) : spec;
+    const parts = body.split(":");
+    if (parts.length < 2) return spec;
+    const source = parts[0];
+    if (isHostPathSource(source) || source.startsWith(prefix)) return spec;
+    parts[0] = scopedVolumeName(slug, source);
+    return parts.join(":") + mode;
+  });
+}
+
+// ../../packages/adapters/src/runtime/docker-ssh-agent.ts
+import net from "net";
+var DEFAULT_REMOTE_DOCKER_SOCKET_PATH = "/var/run/docker.sock";
+var resolvedDockerSocketPathCache = /* @__PURE__ */ new WeakMap();
+var DOCKER_DIAL_STDIO_COMMAND = "docker system dial-stdio";
+var STREAMLOCAL_PROBE_TIMEOUT_MS = 8e3;
+function toSshConfig(opts) {
+  return {
+    host: opts.host ?? "",
+    port: opts.port ?? 22,
+    username: opts.username,
+    hostVerifier: opts.hostVerifier,
+    password: opts.password,
+    privateKey: opts.privateKey,
+    privateKeyPassphrase: opts.privateKeyPassphrase,
+    sshAgent: opts.sshAgent
+  };
+}
+function getConfiguredDockerSocketPath(opts) {
+  const socketPath = opts.dockerSocketPath?.trim();
+  return socketPath ? socketPath : null;
+}
+function normalizeSocketPathLines(lines) {
+  const seen = /* @__PURE__ */ new Set();
+  const normalized = [];
+  for (const line of lines) {
+    const socketPath = line.trim();
+    if (!socketPath.startsWith("/")) {
+      continue;
+    }
+    if (seen.has(socketPath)) {
+      continue;
+    }
+    seen.add(socketPath);
+    normalized.push(socketPath);
+  }
+  return normalized;
+}
+var DOCKER_SOCKET_DISCOVERY_SCRIPT = [
+  "set -eu",
+  'uid="$(id -u 2>/dev/null || printf 0)"',
+  'printf "%s\\n" "/var/run/docker.sock" "/run/docker.sock" "/run/podman/podman.sock" "/run/user/$uid/docker.sock" "$HOME/.docker/run/docker.sock" | while IFS= read -r candidate; do if [ -S "$candidate" ]; then printf "%s\\n" "$candidate"; fi; done',
+  "find /run/user -maxdepth 2 -type s \\( -name docker.sock -o -name podman.sock \\) -print 2>/dev/null || true",
+  'for dir in /run /var/run "$HOME/.docker/run"; do',
+  '  if [ -d "$dir" ]; then',
+  '    find "$dir" -maxdepth 3 -type s \\( -name docker.sock -o -name podman.sock \\) -print 2>/dev/null || true',
+  "  fi",
+  "done"
+].join("\n");
+async function discoverRemoteDockerSocketPathsWithClient(client) {
+  const result = await execSshCommand(client, DOCKER_SOCKET_DISCOVERY_SCRIPT);
+  const lines = [result.stdout, result.stderr].filter(Boolean).flatMap((text) => text.split(/\r?\n/)).map((line) => line.trim()).filter(Boolean);
+  return normalizeSocketPathLines(lines);
+}
+async function discoverRemoteDockerSocketPathsWithExecutor(executor) {
+  try {
+    const output = await executor.exec(DOCKER_SOCKET_DISCOVERY_SCRIPT, { timeout: 1e4 });
+    return normalizeSocketPathLines(output.split(/\r?\n/));
+  } catch {
+    return [];
+  }
+}
+async function discoverRemoteDockerSocketPaths(opts) {
+  if (opts.executor) {
+    return discoverRemoteDockerSocketPathsWithExecutor(opts.executor);
+  }
+  let conn = null;
+  try {
+    conn = await connectSshClient(toSshConfig(opts));
+    return await discoverRemoteDockerSocketPathsWithClient(conn);
+  } finally {
+    conn?.end();
+  }
+}
+async function resolveRemoteDockerSocketPath(opts) {
+  const configuredSocketPath = getConfiguredDockerSocketPath(opts);
+  if (configuredSocketPath) {
+    return configuredSocketPath;
+  }
+  const cachedPath = resolvedDockerSocketPathCache.get(opts);
+  if (cachedPath) {
+    return cachedPath;
+  }
+  const pendingPath = discoverRemoteDockerSocketPaths(opts).then((paths) => paths[0] ?? DEFAULT_REMOTE_DOCKER_SOCKET_PATH).catch(() => DEFAULT_REMOTE_DOCKER_SOCKET_PATH);
+  resolvedDockerSocketPathCache.set(opts, pendingPath);
+  return pendingPath;
+}
+async function openStreamlocalUpstream(opts) {
+  const socketPath = await resolveRemoteDockerSocketPath(opts);
+  if (opts.executor?.forwardUnixSocket) {
+    return opts.executor.forwardUnixSocket(socketPath);
+  }
+  const client = await connectSshClient(toSshConfig(opts));
+  try {
+    const channel = await openSshUnixSocket(client, socketPath);
+    channel.once("close", () => client.end());
+    channel.on("error", () => client.end());
+    return channel;
+  } catch (error) {
+    client.end();
+    throw error;
+  }
+}
+function createDockerSshBridge(opts) {
+  const clients = /* @__PURE__ */ new Set();
+  let upstreamMode = null;
+  let modeDecision = null;
+  let dialClient = null;
+  const openDialStdioUpstream = async () => {
+    if (opts.executor?.openDockerDialStdio) {
+      const stream = await opts.executor.openDockerDialStdio();
+      stream.once(
+        "error",
+        (e) => console.warn(`[docker-ssh] dial-stdio channel error: ${safeErrorMessage(e)}`)
+      );
+      return stream;
+    }
+    if (!dialClient) {
+      const client = await connectSshClient(toSshConfig(opts));
+      client.once("close", () => {
+        if (dialClient === client) dialClient = null;
+      });
+      dialClient = client;
+    }
+    return openSshExecChannel(dialClient, DOCKER_DIAL_STDIO_COMMAND);
+  };
+  const decideMode = async () => {
+    let probe = null;
+    try {
+      probe = await withTimeout(
+        openStreamlocalUpstream(opts),
+        STREAMLOCAL_PROBE_TIMEOUT_MS,
+        `streamlocal open timed out after ${STREAMLOCAL_PROBE_TIMEOUT_MS / 1e3}s`
+      );
+      const stream = probe;
+      const flowed = await new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(false), STREAMLOCAL_PROBE_TIMEOUT_MS);
+        const settle = (ok) => {
+          clearTimeout(timer);
+          resolve(ok);
+        };
+        stream.once("data", () => settle(true));
+        stream.once("error", () => settle(false));
+        stream.once("close", () => settle(false));
+        try {
+          stream.write("GET /_ping HTTP/1.0\r\nHost: localhost\r\n\r\n");
+        } catch {
+          settle(false);
+        }
+      });
+      if (flowed) {
+        console.log(`[docker-ssh] upstream=streamlocal (${opts.host ?? "?"})`);
+        return "streamlocal";
+      }
+      console.warn(
+        `[docker-ssh] upstream=dial-stdio (${opts.host ?? "?"}) \u2014 streamlocal opened but no data flowed (Bun/ssh2)`
+      );
+      return "dialstdio";
+    } catch (err) {
+      console.warn(
+        `[docker-ssh] upstream=dial-stdio (${opts.host ?? "?"}) \u2014 streamlocal unavailable: ${safeErrorMessage(err)}`
+      );
+      return "dialstdio";
+    } finally {
+      probe?.destroy();
+    }
+  };
+  const ensureMode = () => {
+    if (upstreamMode) return Promise.resolve(upstreamMode);
+    modeDecision ??= decideMode().then((mode) => upstreamMode = mode);
+    return modeDecision;
+  };
+  const openUpstream = async () => {
+    const mode = await ensureMode();
+    return mode === "dialstdio" ? openDialStdioUpstream() : openStreamlocalUpstream(opts);
+  };
+  const server = net.createServer((client) => {
+    clients.add(client);
+    client.setNoDelay(true);
+    client.once("close", () => clients.delete(client));
+    openUpstream().then((upstream) => {
+      const teardown = () => {
+        client.destroy();
+        upstream.destroy();
+      };
+      client.on("error", teardown);
+      upstream.on("error", teardown);
+      client.once("close", () => upstream.destroy());
+      upstream.once("close", () => client.destroy());
+      client.pipe(upstream);
+      upstream.pipe(client);
+    }).catch((error) => {
+      console.warn(`[docker-ssh] bridge upstream open failed: ${safeErrorMessage(error)}`);
+      client.destroy(error instanceof Error ? error : new Error(String(error)));
+    });
+  });
+  return {
+    start: () => new Promise((resolve, reject) => {
+      const onError = (error) => reject(error);
+      server.once("error", onError);
+      server.listen(0, "127.0.0.1", () => {
+        server.removeListener("error", onError);
+        const address = server.address();
+        if (address === null || typeof address === "string") {
+          reject(new Error("Docker SSH bridge failed to bind a loopback TCP port."));
+          return;
+        }
+        resolve({ host: "127.0.0.1", port: address.port });
+      });
+    }),
+    probe: async () => {
+      await ensureMode();
+    },
+    close: () => {
+      for (const client of clients) {
+        client.destroy();
+      }
+      clients.clear();
+      dialClient?.end();
+      dialClient = null;
+      server.close();
+    }
+  };
+}
+
+// ../../packages/adapters/src/runtime/docker-transport.ts
+function resolveDockerTransport(opts) {
+  if (!opts || !opts.transport || opts.transport === "socket") {
+    return {
+      kind: "socket",
+      description: "local Docker daemon via socket",
+      unreachableHint: "Check that the local Docker daemon is running.",
+      establish: async () => ({ socketPath: "/var/run/docker.sock" }),
+      close: async () => {
+      },
+      preflight: async () => {
+      }
+    };
+  }
+  if (opts.transport === "ssh") {
+    if (!opts.privateKey && !opts.sshAgent && !opts.password) {
+      throw new Error("SSH transport requires one of privateKey, sshAgent, or password.");
+    }
+    let bridge = null;
+    return {
+      kind: "ssh",
+      description: `remote Docker daemon via SSH (${opts.host ?? "unknown-host"})`,
+      unreachableHint: "Check that SSH credentials are correct, Docker is running on the server, and the SSH user can access the Docker daemon (in the `docker` group or root). The transport uses SSH socket forwarding where available and falls back to `docker system dial-stdio` over an exec channel otherwise.",
+      establish: async () => {
+        bridge = createDockerSshBridge(opts);
+        const { host, port } = await bridge.start();
+        return {
+          protocol: "http",
+          host,
+          port,
+          timeout: opts.timeout ?? 6e5
+        };
+      },
+      close: async () => {
+        bridge?.close();
+        bridge = null;
+      },
+      // Decide the upstream transport (streamlocal vs dial-stdio) up front so
+      // the daemon `ping()` in assertReachable runs over the working one. The
+      // ping itself is the real reachability check.
+      preflight: async () => {
+        await bridge?.probe();
+      }
+    };
+  }
+  if (!opts.ca || !opts.cert || !opts.key) {
+    throw new Error(
+      "TCP transport requires ca, cert, and key for mutual TLS. Plaintext TCP connections are not supported for security reasons."
+    );
+  }
+  return {
+    kind: "tcp",
+    description: `remote Docker daemon via TLS (${opts.host ?? "unknown-host"}:${opts.port ?? 2376})`,
+    unreachableHint: "Check that the remote Docker daemon is reachable and the TLS certificates are valid.",
+    establish: async () => ({
+      protocol: "https",
+      host: opts.host,
+      port: opts.port ?? 2376,
+      ca: opts.ca,
+      cert: opts.cert,
+      key: opts.key,
+      timeout: opts.timeout ?? 3e4
+    }),
+    close: async () => {
+    },
+    preflight: async () => {
+    }
+  };
+}
+
+// ../../packages/adapters/src/runtime/docker.ts
+var isDockerNotFoundError = isRuntimeNotFoundError;
+function clampShellWindow(value, fallback, min, max) {
+  const n = Number.isFinite(value) ? Number(value) : fallback;
+  if (n < min) return min;
+  if (n > max) return max;
+  return Math.floor(n);
+}
+var RESTART_POLICIES = {
+  always: { Name: "always", MaximumRetryCount: 0 },
+  "on-failure": { Name: "on-failure", MaximumRetryCount: 5 },
+  "unless-stopped": { Name: "unless-stopped", MaximumRetryCount: 0 },
+  no: { Name: "no", MaximumRetryCount: 0 }
+};
+var DOCKER_BUILD_IDLE_TIMEOUT_MS = 30 * 60 * 1e3;
+function resolveRestartPolicy(policy) {
+  return RESTART_POLICIES[policy ?? "always"] ?? RESTART_POLICIES.always;
+}
+function normalizeDockerMount(m) {
+  return {
+    type: m.Type ?? "volume",
+    ...m.Name ? { name: m.Name } : {},
+    ...m.Source ? { source: m.Source } : {},
+    destination: m.Destination ?? "",
+    rw: m.RW !== false
+  };
+}
+function toStringArray(v) {
+  if (v == null) return void 0;
+  const arr = Array.isArray(v) ? v : [v];
+  return arr.length > 0 ? arr : void 0;
+}
+function normalizeInspectPorts(data) {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  const parseKey = (key) => {
+    const [portStr, proto] = key.split("/");
+    const port = Number(portStr);
+    return Number.isFinite(port) ? { port, proto: proto || "tcp" } : null;
+  };
+  const nsPorts = data.NetworkSettings?.Ports ?? {};
+  for (const [key, bindings] of Object.entries(nsPorts)) {
+    const parsed = parseKey(key);
+    if (!parsed) continue;
+    seen.add(key);
+    if (bindings && bindings.length > 0) {
+      for (const b of bindings) {
+        out.push({
+          privatePort: parsed.port,
+          ...b.HostPort ? { publicPort: Number(b.HostPort) } : {},
+          type: parsed.proto,
+          ...b.HostIp ? { ip: b.HostIp } : {}
+        });
+      }
+    } else {
+      out.push({ privatePort: parsed.port, type: parsed.proto });
+    }
+  }
+  const hostBindings = data.HostConfig?.PortBindings ?? {};
+  for (const [key, bindings] of Object.entries(hostBindings)) {
+    if (seen.has(key)) continue;
+    const parsed = parseKey(key);
+    if (!parsed) continue;
+    seen.add(key);
+    if (bindings && bindings.length > 0) {
+      for (const b of bindings) {
+        out.push({
+          privatePort: parsed.port,
+          ...b.HostPort ? { publicPort: Number(b.HostPort) } : {},
+          type: parsed.proto,
+          ...b.HostIp ? { ip: b.HostIp } : {}
+        });
+      }
+    } else {
+      out.push({ privatePort: parsed.port, type: parsed.proto });
+    }
+  }
+  const exposed = data.Config?.ExposedPorts ?? {};
+  for (const key of Object.keys(exposed)) {
+    if (seen.has(key)) continue;
+    const parsed = parseKey(key);
+    if (parsed) out.push({ privatePort: parsed.port, type: parsed.proto });
+  }
+  return out;
+}
+function parsePortBindings(portSpecs) {
+  const exposedPorts = {};
+  const portBindings = {};
+  for (const spec of portSpecs) {
+    const slashIdx = spec.lastIndexOf("/");
+    const rawProto = slashIdx >= 0 ? spec.slice(slashIdx + 1).toLowerCase() : "";
+    const protocol = rawProto === "udp" || rawProto === "sctp" ? rawProto : "tcp";
+    const mapping = slashIdx >= 0 ? spec.slice(0, slashIdx) : spec;
+    const parts = mapping.split(":");
+    if (parts.length === 1) {
+      const key = `${parts[0]}/${protocol}`;
+      exposedPorts[key] = {};
+      portBindings[key] = [{ HostPort: "" }];
+    } else {
+      const containerPort = parts[parts.length - 1];
+      const hostPort = parts[parts.length - 2];
+      const hostIp = parts.length > 2 ? parts.slice(0, -2).join(":") : void 0;
+      const key = `${containerPort}/${protocol}`;
+      exposedPorts[key] = {};
+      portBindings[key] = [hostIp ? { HostIp: hostIp, HostPort: hostPort } : { HostPort: hostPort }];
+    }
+  }
+  return { exposedPorts, portBindings };
+}
+var DURATION_UNITS_NS = {
+  ns: 1,
+  us: 1e3,
+  "\xB5s": 1e3,
+  ms: 1e6,
+  s: 1e9,
+  m: 6e10,
+  h: 36e11
+};
+function parseDurationNs(value) {
+  if (value == null) return void 0;
+  const str = String(value).trim();
+  if (!str) return void 0;
+  if (/^\d+(\.\d+)?$/.test(str)) return Math.round(parseFloat(str) * 1e9);
+  const re = /(\d+(?:\.\d+)?)(ns|us|µs|ms|s|m|h)/g;
+  let total = 0;
+  let matched = false;
+  let m;
+  while ((m = re.exec(str)) !== null) {
+    matched = true;
+    total += parseFloat(m[1]) * DURATION_UNITS_NS[m[2]];
+  }
+  return matched ? Math.round(total) : void 0;
+}
+function toDockerHealthcheck(hc) {
+  if (!hc) return void 0;
+  if (hc.disable) return { Test: ["NONE"] };
+  let Test;
+  if (typeof hc.test === "string" && hc.test.trim()) {
+    Test = ["CMD-SHELL", hc.test];
+  } else if (Array.isArray(hc.test) && hc.test.length > 0) {
+    Test = ["CMD", ...hc.test];
+  }
+  if (!Test) return void 0;
+  const Interval = parseDurationNs(hc.interval);
+  const Timeout = parseDurationNs(hc.timeout);
+  const StartPeriod = parseDurationNs(hc.startPeriod);
+  return {
+    Test,
+    ...Interval !== void 0 && { Interval },
+    ...Timeout !== void 0 && { Timeout },
+    ...typeof hc.retries === "number" && { Retries: hc.retries },
+    ...StartPeriod !== void 0 && { StartPeriod }
+  };
+}
+function hasDockerFrameHeader(buf, offset = 0) {
+  return buf.length >= offset + 8 && (buf[offset] === 1 || buf[offset] === 2) && buf[offset + 1] === 0 && buf[offset + 2] === 0 && buf[offset + 3] === 0;
+}
+function stripDockerHeaders(buf) {
+  const lines = [];
+  let offset = 0;
+  while (offset < buf.length) {
+    if (hasDockerFrameHeader(buf, offset)) {
+      const size = buf.readUInt32BE(offset + 4);
+      lines.push(buf.subarray(offset + 8, offset + 8 + size).toString("utf-8"));
+      offset += 8 + size;
+    } else {
+      lines.push(buf.subarray(offset).toString("utf-8"));
+      break;
+    }
+  }
+  return lines.join("");
+}
+function stripDockerChunkHeader(chunk) {
+  return hasDockerFrameHeader(chunk) ? chunk.subarray(8) : chunk;
+}
+function parseTimestampedLine(line) {
+  const spaceIdx = line.indexOf(" ");
+  return {
+    timestamp: spaceIdx > 0 ? line.slice(0, spaceIdx) : (/* @__PURE__ */ new Date()).toISOString(),
+    message: spaceIdx > 0 ? line.slice(spaceIdx + 1) : line
+  };
+}
+function firstNetworkIp(networks) {
+  for (const net2 of Object.values(networks ?? {})) {
+    if (net2?.IPAddress) return net2.IPAddress;
+  }
+  return void 0;
+}
+function extractNetworkInfo(data) {
+  let ip;
+  for (const net2 of Object.values(data.NetworkSettings.Networks ?? {})) {
+    if (net2.IPAddress) {
+      ip = net2.IPAddress;
+      break;
+    }
+  }
+  let hostPort;
+  for (const bindings of Object.values(data.NetworkSettings.Ports ?? {})) {
+    if (bindings?.[0]?.HostPort) {
+      hostPort = parseInt(bindings[0].HostPort, 10);
+      break;
+    }
+  }
+  return { ip, hostPort };
+}
+function parseLoadedImageRef(output) {
+  const matches = [...(output || "").matchAll(/Loaded image(?: ID)?:\s*(\S+)/gi)];
+  return matches.length ? matches[matches.length - 1][1].trim() : void 0;
+}
+var DockerRuntime = class _DockerRuntime {
+  name = "docker";
+  capabilities = /* @__PURE__ */ new Set([
+    "build",
+    "deploy",
+    "multiServiceDeploy",
+    "stop",
+    "start",
+    "restart",
+    "destroy",
+    "containerInfo",
+    "runtimeLogs",
+    "streamLogs",
+    "usage",
+    "containerIp",
+    "rollback",
+    "serviceShell",
+    "projectContainerSweep",
+    "deploymentContainerQuery",
+    "hostContainerQuery"
+  ]);
+  /** Docker honors every extended compose key we currently support. */
+  unsupportedComposeKeys = /* @__PURE__ */ new Set();
+  _docker;
+  /** Underlying dockerode instance - exposed for advanced usage */
+  get docker() {
+    return this._docker;
+  }
+  /** Connection config this runtime was created with */
+  connectionOptions;
+  /** Resolved transport - single switch point for socket / ssh / tcp */
+  transport;
+  systemManager;
+  provisionLock;
+  constructor(opts, systemManager, provisionLock) {
+    this.connectionOptions = opts;
+    this.transport = resolveDockerTransport(opts);
+    this.systemManager = systemManager ?? null;
+    this.provisionLock = provisionLock;
+  }
+  /**
+   * Build a runtime and stand up its transport. Async because the SSH
+   * transport binds a loopback bridge whose port is only known after listen();
+   * socket/TCP transports resolve their options synchronously.
+   */
+  static async create(opts, systemManager, provisionLock) {
+    const runtime = new _DockerRuntime(opts, systemManager, provisionLock);
+    runtime._docker = new Dockerode(await runtime.transport.establish());
+    return runtime;
+  }
+  supports(cap) {
+    return this.capabilities.has(cap);
+  }
+  async dispose() {
+    await this.transport.close();
+  }
+  // ─── Health check ──────────────────────────────────────────────────
+  /** Ping the Docker daemon - useful for connection testing */
+  async ping() {
+    try {
+      await this.assertReachable();
+      return true;
+    } catch (err) {
+      console.warn(`[docker] daemon unreachable: ${safeErrorMessage(err)}`);
+      return false;
+    }
+  }
+  /**
+   * Assert the Docker daemon is reachable, RETHROWING the underlying error
+   * instead of collapsing it to false. For the SSH transport, `preflight()`
+   * decides the upstream transport (SSH socket forwarding where it works, else
+   * `docker system dial-stdio` over an exec channel — the streamlocal-free path
+   * the Bun-compiled desktop needs), then `ping()` is the real end-to-end check
+   * over that transport. Use on user-facing paths (e.g. the migration scan) so
+   * the real cause reaches the user instead of a generic "not reachable".
+   */
+  async assertReachable() {
+    await this.ensureDockerFeature();
+    await this.transport.preflight();
+    await this.docker.ping();
+  }
+  async ensureDockerFeature(logger) {
+    if (!this.systemManager) {
+      return;
+    }
+    await this.systemManager.ensureFeature("deploy", (entry) => {
+      logger?.log(entry.message, entry.level);
+    });
+  }
+  /** Get Docker daemon info (version, platform, etc.) */
+  async info() {
+    return this.docker.info();
+  }
+  // ── Image naming ────────────────────────────────────────────────────────
+  /** Canonical image tag for a build session. */
+  imageTag(slug, sessionId) {
+    const name = slug ? `openship/${slug}` : `openship/build`;
+    return `${name}:${sessionId}`;
+  }
+  /** Labels applied to both build images and deploy containers. */
+  labels(config) {
+    const l = {
+      "openship.project": config.projectId
+    };
+    if (config.deploymentId) l["openship.deployment"] = config.deploymentId;
+    if (config.sessionId) l["openship.build"] = config.sessionId;
+    return l;
+  }
+  // ── Build lifecycle ────────────────────────────────────────────────────
+  /**
+   * Sum the byte size of a directory tree. Best-effort - used only for a
+   * human-readable "X MB context streamed" log line. Returns 0 if the
+   * walk hits an error rather than failing the build.
+   */
+  async estimateContextSize(dir) {
+    const { stat, readdir } = await import("fs/promises");
+    const { join } = await import("path");
+    let total = 0;
+    const stack = [dir];
+    while (stack.length) {
+      const current = stack.pop();
+      let entries;
+      try {
+        entries = await readdir(current, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      for (const entry of entries) {
+        const full = join(current, entry.name);
+        if (entry.isDirectory()) {
+          stack.push(full);
+        } else if (entry.isFile()) {
+          try {
+            const s = await stat(full);
+            total += s.size;
+          } catch {
+          }
+        }
+      }
+    }
+    return total;
+  }
+  emitDockerStep(logger, step, status, message) {
+    const label = status === "running" ? "\u2192" : status === "completed" ? "\u2713" : "\u21B7";
+    logger.log(`[${step}] ${label} ${message}`);
+    logger.step(step, status, message);
+  }
+  handleBuildEvent(event, logger) {
+    const errorMessage = event.errorDetail?.message ?? event.error;
+    if (errorMessage) {
+      logger.log(errorMessage, "error");
+      return errorMessage;
+    }
+    if (event.stream) {
+      const line = event.stream.trim();
+      if (!line) return null;
+      const marker = line.match(
+        /^\[openship-build\]\s+step=(clone|install|build)\s+status=(running|completed|skipped)$/
+      );
+      if (marker) {
+        const [, step, status] = marker;
+        this.emitDockerStep(
+          logger,
+          step,
+          status,
+          line
+        );
+        if (status === "completed" && step === "install") {
+          logger.log("Finalizing image (layer commit + tag)...");
+        }
+        return null;
+      }
+      if (this.isLowSignalDockerLine(line)) {
+        return null;
+      }
+      logger.log(line, parseLogLevel(line));
+      return this.extractBuildFailureHint(line);
+    }
+    if (event.status) {
+      const parts = [event.id, event.status, event.progress].filter((p) => Boolean(p?.trim())).map((p) => p.trim());
+      if (parts.length) logger.log(parts.join(" "));
+    }
+    return null;
+  }
+  // Only the truly-redundant lines get filtered. We KEEP "Step N/M : ..."
+  // because that's the user's best progress signal during a long build -
+  // it shows which Dockerfile instruction is currently executing.
+  //
+  // Removed (= now passes through to terminal):
+  //   - "Step N/M : ..."  → high-signal, shows progress
+  //   - "Successfully built / tagged" → confirms success
+  //
+  // Still filtered (= noise):
+  //   - "---> hash"       → opaque layer hash, no signal for users
+  //   - "Running in ..."  → intermediate container id, no signal
+  //   - "Removing intermediate container ..." → cleanup chatter
+  static DOCKER_BUILDER_NOISE = [
+    /^--->/i,
+    // ---> abc123def
+    /^Running in\s+[a-f0-9]{6,}$/i,
+    /^Removing intermediate container\s+[a-f0-9]{6,}$/i
+  ];
+  isLowSignalDockerLine(line) {
+    return _DockerRuntime.DOCKER_BUILDER_NOISE.some((p) => p.test(line));
+  }
+  extractBuildFailureHint(line) {
+    if (/returned a non-zero code:\s*\d+/i.test(line)) {
+      return line;
+    }
+    if (/\/workspace\/package\.json/i.test(line) && /ENOENT/i.test(line)) {
+      return "Docker build ran from /workspace but package.json was not found there. The configured rootDirectory is likely empty or incorrect.";
+    }
+    if (/failed to solve|executor failed running|error: build/i.test(line)) {
+      return line;
+    }
+    return null;
+  }
+  formatDockerConnectivityError(error) {
+    const message = safeErrorMessage(error);
+    if (/^Cannot reach Docker daemon:/i.test(message)) {
+      return message;
+    }
+    return `Cannot reach Docker daemon: ${message}. ${this.transport.unreachableHint}`;
+  }
+  /**
+   * SSH transport build path. Bypasses dockerode's HTTP-over-SSH upload
+   * (which is ~1-2 MB/s and silent) in favor of two well-trodden pieces:
+   *
+   *   1. `transferLocalDirectory(...)` - defaults to rsync over the
+   *      SYSTEM `ssh` binary (NOT the Node `ssh2` library), with native
+   *      `--progress` output streamed straight from rsync. ~10-30 MB/s
+   *      typical. Lands the context at `/tmp/openship-build-<sessionId>`
+   *      on remote. Falls back to tar through the ssh2 channel only if
+   *      rsync isn't installed on either side.
+   *
+   *   2. `executor.streamExec("docker build ...")` - runs native docker
+   *      CLI on the remote. Its raw stdout/stderr streams back unfiltered
+   *      so the user sees real "Step N/M : ...", layer hashes, install
+   *      output, etc. Same logs you'd see SSHing in and running it by hand.
+   *
+   * Container lifecycle (deploy, stop, logs, etc.) still uses dockerode -
+   * only the slow build upload moves to this path.
+   */
+  /**
+   * Ship a prepared context dir to the remote host (rsync via system ssh with
+   * native --progress; tar/ssh2 fallback). Reused by both the single-image SSH
+   * build and the batch build (which transfers the shared context ONCE).
+   */
+  async transferBuildContext(contextDir, remoteContextDir, log) {
+    const executor = this.connectionOptions?.executor;
+    if (!executor) throw new Error("SSH build path requires an executor on connectionOptions");
+    log.log(`Streaming build context to ${remoteContextDir}...`);
+    await executor.exec(`rm -rf ${sq(remoteContextDir)} && mkdir -p ${sq(remoteContextDir)}`);
+    await transferLocalDirectory(
+      contextDir,
+      { kind: "executor", executor, path: remoteContextDir },
+      log,
+      { excludes: [] }
+    );
+  }
+  /**
+   * Run native `docker build` on the remote host against an already-transferred
+   * context dir. One image; `dockerfileName` selects which Dockerfile in the
+   * shared tree to use (so N services can build from one transferred context).
+   */
+  async buildImageOnRemote(config, remoteContextDir, dockerfileName, tag, log) {
+    const executor = this.connectionOptions?.executor;
+    if (!executor) throw new Error("SSH build path requires an executor on connectionOptions");
+    const buildArgs = Object.entries({
+      ...config.envVars,
+      NODE_ENV: "production"
+    }).filter(([k]) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(k)).map(([k, v]) => `--build-arg ${sq(`${k}=${v}`)}`).join(" ");
+    const labelArgs = Object.entries(
+      this.labels({ projectId: config.projectId, sessionId: config.sessionId })
+    ).map(([k, v]) => `--label ${sq(`${k}=${v}`)}`).join(" ");
+    const dockerfileFlag = dockerfileName && dockerfileName !== "Dockerfile" ? ` -f ${sq(dockerfileName)}` : "";
+    const buildCmd = `cd ${sq(remoteContextDir)} && docker build --progress=plain -t ${sq(tag)}${dockerfileFlag} ${labelArgs} ${buildArgs} --force-rm .`;
+    log.log(`Running on remote: ${buildCmd}`);
+    log.log("\u2500\u2500\u2500 docker build output \u2500\u2500\u2500");
+    this.emitDockerStep(log, "install", "running", "Running install inside container (docker build)");
+    const { code } = await executor.streamExec(buildCmd, (entry) => {
+      log.log(entry.message, parseLogLevel(entry.message));
+    });
+    log.log("\u2500\u2500\u2500 end docker build output \u2500\u2500\u2500");
+    if (code !== 0) throw new Error(`docker build exited with code ${code}`);
+    this.emitDockerStep(log, "install", "completed", "Image build finished");
+  }
+  /**
+   * Clone the repo directly ON the remote host into `remoteContextDir` — the
+   * clone-on-server alternative to transferBuildContext (which clones on the
+   * orchestrator and rsyncs the tree). Runs `git clone` in a remote host shell,
+   * mirroring the bare runtime (build-pipeline.ts): the credential-helper relay
+   * (`config.gitCredentialHelperPath` — plain URL, nothing persisted) when set,
+   * else `injectGitToken(...)`. Strips `.git` so it never ships into the image.
+   */
+  async cloneSourceOnRemote(config, remoteContextDir, log) {
+    const executor = this.connectionOptions?.executor;
+    if (!executor) throw new Error("Clone-on-server requires an SSH executor on connectionOptions");
+    const useHelper = !!config.gitCredentialHelperPath;
+    if (!useHelper && !config.gitSsh && !config.gitAmbient) {
+      const ref = config.commitSha || config.branch;
+      const tarUrl = githubTarballUrl(config.repoUrl, ref);
+      if (tarUrl) {
+        try {
+          log.log(`Fetching ${config.repoUrl} tarball on the server \u2192 ${remoteContextDir}...
+`);
+          await downloadTarballOnRemote(executor, {
+            url: tarUrl,
+            token: config.gitToken,
+            destDir: remoteContextDir,
+            onLog: (entry) => log.log(entry.message, parseLogLevel(entry.message))
+          });
+          await executor.exec(`rm -rf ${sq(`${remoteContextDir}/.git`)}`).catch(() => {
+          });
+          return;
+        } catch (err) {
+          log.log(
+            `Tarball download failed (${safeErrorMessage(err)}); falling back to git clone.
+`,
+            "warn"
+          );
+        }
+      }
+    }
+    let sshMaterial;
+    if (config.gitSsh) {
+      sshMaterial = await materializeGitSsh(
+        shellGitSshWriter({
+          exec: (cmd) => executor.exec(cmd),
+          writeSecret: (path, content) => executor.writeFile(path, content)
+        }),
+        `${remoteContextDir}.gitssh`,
+        config.gitSsh
+      );
+    }
+    const { cloneUrl, gitEnv: GIT_ENV, credFlag: CRED } = assembleGitClone({
+      repoUrl: config.repoUrl,
+      gitToken: config.gitToken,
+      gitCredentialHelperPath: config.gitCredentialHelperPath,
+      ssh: sshMaterial,
+      ambient: config.gitAmbient
+    });
+    const dir = sq(remoteContextDir);
+    const authLabel = config.gitSsh ? "ssh key" : useHelper ? "forwarded credentials" : config.gitAmbient ? `the server's own git credentials (${config.gitAmbient.via})` : "token";
+    log.log(`Cloning ${config.repoUrl} on the server \u2192 ${remoteContextDir} (${authLabel})...
+`);
+    await executor.exec(`rm -rf ${dir} && mkdir -p ${dir}`);
+    const run = async (cmd) => {
+      const { code } = await executor.streamExec(
+        cmd,
+        (entry) => log.log(entry.message, parseLogLevel(entry.message))
+      );
+      if (code !== 0) throw new Error(`git clone on server exited with code ${code}`);
+    };
+    try {
+      if (config.commitSha) {
+        try {
+          await run(
+            `${GIT_ENV} git ${CRED} clone --progress --depth 50 --branch ${sq(config.branch)} ${sq(cloneUrl)} ${dir} && cd ${dir} && git ${CRED} -c advice.detachedHead=false checkout ${sq(config.commitSha)}`
+          );
+        } catch {
+          log.log(`Commit ${config.commitSha} not in the shallow clone; unshallowing and retrying.
+`, "warn");
+          await run(
+            `cd ${dir} && ${GIT_ENV} git ${CRED} fetch --progress --unshallow && git ${CRED} -c advice.detachedHead=false checkout ${sq(config.commitSha)}`
+          );
+        }
+      } else {
+        await run(
+          `${GIT_ENV} git ${CRED} clone --progress --depth 1 --branch ${sq(config.branch)} ${sq(cloneUrl)} ${dir}`
+        );
+      }
+      await executor.exec(`rm -rf ${sq(`${remoteContextDir}/.git`)}`).catch(() => {
+      });
+    } finally {
+      await sshMaterial?.cleanup();
+    }
+  }
+  /**
+   * Resolve the Dockerfile for a build whose source lives on the REMOTE host
+   * (clone-on-server). Mirrors resolveServiceDockerfile but probes the remote
+   * tree with `test -f` instead of the local FS: a repository Dockerfile
+   * candidate is used when present; otherwise a Dockerfile is generated locally
+   * (pure fn) and written to the remote tree. Returns the dockerfile path
+   * relative to `remoteContextDir`.
+   */
+  async resolveRemoteDockerfile(config, remoteContextDir, generatedName, requireRepositoryDockerfile) {
+    const executor = this.connectionOptions?.executor;
+    if (!executor) throw new Error("Clone-on-server requires an SSH executor on connectionOptions");
+    for (const candidate of resolveDockerfileCandidates(config.rootDirectory, config.dockerfilePath)) {
+      const out = await executor.exec(`test -f ${sq(`${remoteContextDir}/${candidate}`)} && echo yes || true`).catch(() => "");
+      if (out.trim() === "yes") return candidate;
+    }
+    if (requireRepositoryDockerfile) {
+      const expected = config.dockerfilePath?.trim() || "Dockerfile";
+      throw new Error(
+        `No Dockerfile found in the cloned repo. Expected ${expected}${config.rootDirectory ? ` under ${config.rootDirectory}` : ""}.`
+      );
+    }
+    await executor.writeFile(`${remoteContextDir}/${generatedName}`, generateDockerfile(config));
+    return generatedName;
+  }
+  async buildViaSshTarPipe(config, buildContext, tag, log) {
+    const remoteContextDir = `/tmp/openship-build-${config.sessionId}`;
+    try {
+      await this.transferBuildContext(buildContext.contextDir, remoteContextDir, log);
+      await this.buildImageOnRemote(config, remoteContextDir, buildContext.dockerfileName, tag, log);
+    } finally {
+      this.connectionOptions?.executor?.exec(`rm -rf ${sq(remoteContextDir)}`).catch(() => {
+      });
+      await buildContext.cleanup();
+    }
+  }
+  /**
+   * Dockerode build path. Used for local socket and TCP transports, plus
+   * SSH transports that didn't get an executor wired in (shouldn't happen
+   * in normal operation but kept as a safety net).
+   *
+   * This path is slower for SSH (HTTP-over-SSH upload has no streaming),
+   * but it's correct for local/TCP where there's no separate SSH
+   * connection to piggyback on.
+   */
+  async buildViaDockerode(config, buildContext, tag, log) {
+    log.log(`Streaming build context to Docker daemon - image tag: ${tag}`);
+    let stream;
+    try {
+      stream = await this.docker.buildImage(
+        { context: buildContext.contextDir, src: buildContext.contextEntries },
+        {
+          t: tag,
+          dockerfile: buildContext.dockerfileName,
+          labels: this.labels({ projectId: config.projectId, sessionId: config.sessionId }),
+          buildargs: {
+            ...config.envVars,
+            NODE_ENV: "production"
+          },
+          forcerm: true
+        }
+      );
+    } finally {
+      await buildContext.cleanup();
+    }
+    log.log("Connected to Docker daemon. Build output follows:");
+    await this.streamDockerodeBuild(stream, log);
+    log.log("Docker daemon finished streaming build output. Finalizing image...\n");
+  }
+  /**
+   * Consume a dockerode build stream: stream progress to the log, enforce the
+   * idle timeout + keepalive, and throw on a fatal build event. Shared by the
+   * single-image dockerode path and the local batch build (buildImages).
+   */
+  async streamDockerodeBuild(stream, log) {
+    let fatalBuildError = null;
+    await new Promise((resolve, reject) => {
+      let settled = false;
+      let idleTimer = null;
+      let keepaliveTimer = null;
+      let idleMinutes = 0;
+      const clearTimers = () => {
+        if (idleTimer) {
+          clearTimeout(idleTimer);
+          idleTimer = null;
+        }
+        if (keepaliveTimer) {
+          clearInterval(keepaliveTimer);
+          keepaliveTimer = null;
+        }
+        idleMinutes = 0;
+      };
+      const fail = (error) => {
+        if (settled) return;
+        settled = true;
+        clearTimers();
+        stream.destroy?.(error);
+        reject(error);
+      };
+      const succeed = () => {
+        if (settled) return;
+        settled = true;
+        clearTimers();
+        resolve();
+      };
+      const resetIdleTimer = () => {
+        clearTimers();
+        keepaliveTimer = setInterval(() => {
+          idleMinutes += 1;
+          log.log(`Still building... (no output for ${idleMinutes}m)`);
+        }, 6e4);
+        if (keepaliveTimer.unref) keepaliveTimer.unref();
+        idleTimer = setTimeout(() => {
+          fail(new Error(
+            "Docker build produced no output for 30 minutes. This usually means the remote server cannot reach the package registry, has broken DNS, or the Docker daemon stalled during the build."
+          ));
+        }, DOCKER_BUILD_IDLE_TIMEOUT_MS);
+        if (idleTimer.unref) idleTimer.unref();
+      };
+      resetIdleTimer();
+      this.docker.modem.followProgress(
+        stream,
+        (err) => {
+          if (err) {
+            fail(err);
+            return;
+          }
+          succeed();
+        },
+        (event) => {
+          resetIdleTimer();
+          fatalBuildError ??= this.handleBuildEvent(event, log);
+        }
+      );
+    });
+    if (fatalBuildError) {
+      throw new Error(fatalBuildError);
+    }
+  }
+  /**
+   * Confirm a just-built image actually exists before handing its tag back
+   * as the deploy artifact.
+   *
+   * For SSH-transport builds, verify over the SAME pooled SSH exec channel
+   * the `docker build` command itself just ran on — not `this.docker`
+   * (dockerode), which for SSH transport talks over a SEPARATE, independently
+   * -tunneled streamlocal bridge connection (see docker-ssh-agent.ts). That
+   * second connection has proven unreliable in practice: it can hang
+   * indefinitely or report the image missing even though `docker images` on
+   * the box confirms it built successfully seconds earlier. Reusing the
+   * already-proven-live exec channel avoids standing up a second, flakier
+   * connection just to ask a question the first connection already knows
+   * the answer to.
+   *
+   * For local-socket/TCP transports there is no separate bridge — `this.docker`
+   * talks directly to the daemon — so the original dockerode check is fine
+   * and stays as the fallback.
+   */
+  async verifyImageBuilt(tag) {
+    const executor = this.transport.kind === "ssh" ? this.connectionOptions?.executor : null;
+    try {
+      if (executor) {
+        await executor.exec(`docker image inspect ${sq(tag)} >/dev/null`);
+      } else {
+        await this.docker.getImage(tag).inspect();
+      }
+    } catch (cause) {
+      throw new Error(`Docker build finished but the image ${tag} was not created`, { cause });
+    }
+  }
+  async build(config, logger) {
+    const log = logger ?? new BuildLogger();
+    const startTime = Date.now();
+    const tag = this.imageTag(config.slug, config.sessionId);
+    try {
+      log.log(`Build strategy: docker (${this.transport.description})
+`);
+      try {
+        await this.ensureDockerFeature(log);
+      } catch (featureErr) {
+        throw new Error(this.formatDockerConnectivityError(featureErr));
+      }
+      const sshExecutor = this.transport.kind === "ssh" ? this.connectionOptions?.executor : null;
+      if (sshExecutor && config.cloneOnServer) {
+        const remoteContextDir = `/tmp/openship-build-${config.sessionId}`;
+        try {
+          this.emitDockerStep(log, "clone", "running", "Cloning source on the server...");
+          await this.cloneSourceOnRemote(config, remoteContextDir, log);
+          this.emitDockerStep(log, "clone", "completed", "Source cloned on the server");
+          const dockerfileName = await this.resolveRemoteDockerfile(
+            config,
+            remoteContextDir,
+            "Dockerfile.openship",
+            config.stack === "docker"
+          );
+          await this.buildImageOnRemote(config, remoteContextDir, dockerfileName, tag, log);
+        } finally {
+          sshExecutor.exec(`rm -rf ${sq(remoteContextDir)}`).catch(() => {
+          });
+        }
+        await this.verifyImageBuilt(tag);
+        log.log(`Image ${tag} is ready.
+`);
+        log.step("build", "completed", `Finalizing image ${tag}`);
+        return { sessionId: config.sessionId, status: "deploying", imageRef: tag, durationMs: Date.now() - startTime };
+      }
+      this.emitDockerStep(log, "clone", "running", "Preparing Docker build context...");
+      const buildContext = await createDockerBuildContext(config, {
+        requireRepositoryDockerfile: config.stack === "docker",
+        onLog: log.callback
+      });
+      try {
+        const sizeBytes = await this.estimateContextSize(buildContext.contextDir);
+        const sizeMB = (sizeBytes / 1024 / 1024).toFixed(1);
+        this.emitDockerStep(
+          log,
+          "clone",
+          "completed",
+          `Docker build context ready (${sizeMB} MB)`
+        );
+      } catch {
+        this.emitDockerStep(log, "clone", "completed", "Docker build context ready");
+      }
+      if (buildContext.rootDirectory) {
+        log.log(`Using Docker build root: ${buildContext.rootDirectory}`);
+      }
+      if (buildContext.usesRepositoryDockerfile) {
+        this.emitDockerStep(
+          log,
+          "install",
+          "skipped",
+          "Repository Dockerfile owns dependency installation"
+        );
+        this.emitDockerStep(
+          log,
+          "build",
+          "running",
+          "Building image from repository Dockerfile..."
+        );
+      }
+      if (!buildContext.usesRepositoryDockerfile && !config.installCommand) {
+        this.emitDockerStep(log, "install", "skipped", "No install command configured");
+      }
+      if (!buildContext.usesRepositoryDockerfile && !config.buildCommand) {
+        this.emitDockerStep(log, "build", "skipped", "No build command configured");
+      }
+      if (sshExecutor) {
+        await this.buildViaSshTarPipe(config, buildContext, tag, log);
+      } else {
+        await this.buildViaDockerode(config, buildContext, tag, log);
+      }
+      await this.verifyImageBuilt(tag);
+      log.log(`Image ${tag} is ready.
+`);
+      log.log(`[build] \u2713 Image ${tag} ready`);
+      log.step("build", "completed", `Finalizing image ${tag}`);
+      const durationMs = Date.now() - startTime;
+      return { sessionId: config.sessionId, status: "deploying", imageRef: tag, durationMs };
+    } catch (err) {
+      const msg = safeErrorMessage(err);
+      log.step("build", "failed", `Docker build failed: ${msg}`);
+      return { sessionId: config.sessionId, status: "failed", durationMs: Date.now() - startTime, errorMessage: `Docker build failed: ${msg}` };
+    }
+  }
+  /**
+   * Build a STATIC app in a Docker sandbox, then extract its doc-root onto a
+   * host directory the edge serves via nginx `root`. Reuses `build()` — so
+   * Docker is auto-ensured (ensureDockerFeature) and the static nginx image is
+   * produced (`generateStaticDockerfile` COPYs the output to the fixed
+   * `/usr/share/nginx/html`) — then extracts those files and discards the image.
+   * Returns the host dir as `imageRef`, matching BareRuntime.build's host-dir
+   * contract so the existing file-backed serve path (deployStatic /
+   * resolveStaticRoot) consumes it unchanged. Never leaves a long-lived
+   * container: the extraction container is created (not started) and removed.
+   */
+  async buildStaticToHost(config, hostOutDir, logger) {
+    const log = logger ?? new BuildLogger();
+    const buildResult = await this.build({ ...config, isStatic: true }, log);
+    if (buildResult.status !== "deploying" || !buildResult.imageRef) {
+      return buildResult;
+    }
+    const tag = buildResult.imageRef;
+    const extractStart = Date.now();
+    const DOC_ROOT = "/usr/share/nginx/html";
+    try {
+      const sshExecutor = this.transport.kind === "ssh" ? this.connectionOptions?.executor : null;
+      log.log("Extracting static files from the build sandbox...\n");
+      if (sshExecutor) {
+        const cid = (await sshExecutor.exec(`docker create ${sq(tag)}`)).trim();
+        try {
+          await sshExecutor.exec(`mkdir -p ${sq(hostOutDir)}`);
+          await sshExecutor.exec(`docker cp ${sq(`${cid}:${DOC_ROOT}/.`)} ${sq(hostOutDir)}`);
+        } finally {
+          await sshExecutor.exec(`docker rm ${sq(cid)}`).catch(() => {
+          });
+        }
+      } else {
+        const { mkdir } = await import("fs/promises");
+        const { spawn } = await import("child_process");
+        await mkdir(hostOutDir, { recursive: true });
+        const container = await this.docker.createContainer({ Image: tag });
+        try {
+          const tarStream = await container.getArchive({ path: DOC_ROOT });
+          await new Promise((resolve, reject) => {
+            const extract = spawn("tar", ["-x", "--strip-components=1", "-C", hostOutDir]);
+            let errBuf = "";
+            extract.stderr.on("data", (d) => errBuf += d.toString());
+            extract.on("error", reject);
+            tarStream.on("error", reject);
+            tarStream.pipe(extract.stdin);
+            extract.on(
+              "close",
+              (code) => code === 0 ? resolve() : reject(new Error(`static extract failed (tar ${code}): ${errBuf.trim().slice(-500)}`))
+            );
+          });
+        } finally {
+          await container.remove({ force: true }).catch(() => {
+          });
+        }
+      }
+      log.log(`Static files ready at ${hostOutDir}
+`);
+      return {
+        sessionId: config.sessionId,
+        status: "deploying",
+        imageRef: hostOutDir,
+        durationMs: (buildResult.durationMs ?? 0) + (Date.now() - extractStart)
+      };
+    } catch (err) {
+      const msg = safeErrorMessage(err);
+      log.step("build", "failed", `Static extract failed: ${msg}`);
+      return {
+        sessionId: config.sessionId,
+        status: "failed",
+        durationMs: (buildResult.durationMs ?? 0) + (Date.now() - extractStart),
+        errorMessage: `Static extract failed: ${msg}`
+      };
+    } finally {
+      await this.removeImage(tag).catch(() => {
+      });
+    }
+  }
+  /**
+   * Batch build: clone + prune the shared source ONCE, then build every image
+   * from that single tree. For SSH the context is transferred ONCE and each
+   * image builds on the remote against it. Eliminates the per-service re-clone
+   * / re-transfer that N separate build() calls incur — every service builds on
+   * the SAME daemon, so the source only needs to arrive once.
+   *
+   * Prepare-phase logs (clone/transfer) go to `prepareLogger`; each image's
+   * build output goes to its own `spec.logger`.
+   */
+  async buildImages(specs, prepareLogger) {
+    if (specs.length === 0) return [];
+    try {
+      await this.ensureDockerFeature(prepareLogger);
+    } catch (featureErr) {
+      throw new Error(this.formatDockerConnectivityError(featureErr));
+    }
+    const source = specs[0].config;
+    const isSsh = this.transport.kind === "ssh" && !!this.connectionOptions?.executor;
+    const cloneOnServer = isSsh && !!source.cloneOnServer;
+    const remoteContextDir = `/tmp/openship-build-${source.sessionId}`;
+    let tree = null;
+    if (cloneOnServer) {
+      prepareLogger.step("clone", "running", "Cloning source on the server...");
+      await this.cloneSourceOnRemote(source, remoteContextDir, prepareLogger);
+      prepareLogger.step("clone", "completed", "Source cloned on the server");
+    } else {
+      prepareLogger.step("clone", "running", "Preparing shared build context...");
+      tree = await prepareSourceTree(source, { onLog: prepareLogger.callback });
+    }
+    try {
+      const resolvedList = await Promise.all(
+        specs.map(async (spec) => {
+          const generatedName = `Dockerfile.openship.${spec.config.sessionId}`;
+          const requireRepo = spec.requireRepositoryDockerfile ?? spec.config.stack === "docker";
+          try {
+            if (cloneOnServer) {
+              const dockerfileName = await this.resolveRemoteDockerfile(
+                spec.config,
+                remoteContextDir,
+                generatedName,
+                requireRepo
+              );
+              return {
+                spec,
+                dockerfileName,
+                contextEntries: null,
+                error: null
+              };
+            }
+            const resolved = await resolveServiceDockerfile(tree.contextDir, spec.config, {
+              requireRepositoryDockerfile: requireRepo,
+              generatedName
+            });
+            return {
+              spec,
+              dockerfileName: resolved.dockerfileName,
+              contextEntries: resolved.contextEntries,
+              error: null
+            };
+          } catch (err) {
+            return {
+              spec,
+              dockerfileName: null,
+              contextEntries: null,
+              error: safeErrorMessage(err)
+            };
+          }
+        })
+      );
+      if (!cloneOnServer && tree) {
+        try {
+          const sizeBytes = await this.estimateContextSize(tree.contextDir);
+          prepareLogger.step(
+            "clone",
+            "completed",
+            `Shared build context ready (${(sizeBytes / 1024 / 1024).toFixed(1)} MB)`
+          );
+        } catch {
+          prepareLogger.step("clone", "completed", "Shared build context ready");
+        }
+        if (isSsh) {
+          await this.transferBuildContext(tree.contextDir, remoteContextDir, prepareLogger);
+        }
+      }
+      const results = [];
+      for (const { spec, dockerfileName, contextEntries, error } of resolvedList) {
+        const startedAt = Date.now();
+        const tag = this.imageTag(spec.config.slug, spec.config.sessionId);
+        if (error || !dockerfileName) {
+          const result = {
+            sessionId: spec.config.sessionId,
+            status: "failed",
+            durationMs: Date.now() - startedAt,
+            errorMessage: error ?? "Failed to resolve Dockerfile"
+          };
+          spec.onResult?.(result);
+          results.push({ serviceName: spec.serviceName, result });
+          continue;
+        }
+        spec.onStart?.();
+        try {
+          if (isSsh) {
+            await this.buildImageOnRemote(
+              spec.config,
+              remoteContextDir,
+              dockerfileName,
+              tag,
+              spec.logger
+            );
+          } else {
+            const stream = await this.docker.buildImage(
+              { context: tree.contextDir, src: contextEntries ?? [] },
+              {
+                t: tag,
+                dockerfile: dockerfileName,
+                labels: this.labels({
+                  projectId: spec.config.projectId,
+                  sessionId: spec.config.sessionId
+                }),
+                buildargs: { ...spec.config.envVars, NODE_ENV: "production" },
+                forcerm: true
+              }
+            );
+            await this.streamDockerodeBuild(stream, spec.logger);
+          }
+          await this.verifyImageBuilt(tag);
+          spec.logger.log(`Image ${tag} is ready.
+`);
+          const result = {
+            sessionId: spec.config.sessionId,
+            status: "deploying",
+            imageRef: tag,
+            durationMs: Date.now() - startedAt
+          };
+          spec.onResult?.(result);
+          results.push({ serviceName: spec.serviceName, result });
+        } catch (err) {
+          const msg = safeErrorMessage(err);
+          spec.logger.log(`Docker build failed: ${msg}
+`, "error");
+          const result = {
+            sessionId: spec.config.sessionId,
+            status: "failed",
+            durationMs: Date.now() - startedAt,
+            errorMessage: `Docker build failed: ${msg}`
+          };
+          spec.onResult?.(result);
+          results.push({ serviceName: spec.serviceName, result });
+        }
+      }
+      return results;
+    } finally {
+      if (isSsh) {
+        this.connectionOptions?.executor?.exec(`rm -rf ${sq(remoteContextDir)}`).catch(() => {
+        });
+      }
+      if (tree) await tree.cleanup();
+    }
+  }
+  async cancelBuild(sessionId) {
+    const containers = await this.docker.listContainers({
+      all: true,
+      filters: { label: [`openship.build=${sessionId}`] }
+    });
+    for (const c of containers) {
+      try {
+        await this.docker.getContainer(c.Id).remove({ force: true });
+      } catch {
+      }
+    }
+  }
+  async getBuildLogs(sessionId) {
+    void sessionId;
+    return [];
+  }
+  // ── Deploy lifecycle ───────────────────────────────────────────────────
+  async deploy(config, onLog) {
+    const log = onLog ?? (() => {
+    });
+    const imageRef = config.imageRef;
+    if (!imageRef) {
+      throw new Error("Docker deploy requires an imageRef (built image tag)");
+    }
+    const containerName = `openship-${config.runtimeName || config.projectId}-${config.deploymentId}`;
+    const env = [
+      `PORT=${config.port}`,
+      `NODE_ENV=${config.environment === "production" ? "production" : "development"}`,
+      ...Object.entries(config.envVars).map(([k, v]) => `${k}=${v}`)
+    ];
+    const cmd = config.startCommand ? ["sh", "-c", config.startCommand] : void 0;
+    const restartPolicy = resolveRestartPolicy(config.restartPolicy);
+    log({
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      message: `Creating container ${containerName} from ${imageRef}...
+`,
+      level: "info"
+    });
+    const container = await this.docker.createContainer({
+      name: containerName,
+      Image: imageRef,
+      Cmd: cmd,
+      Env: env,
+      Labels: this.labels({
+        deploymentId: config.deploymentId,
+        projectId: config.projectId
+      }),
+      ExposedPorts: { [`${config.port}/tcp`]: {} },
+      HostConfig: {
+        RestartPolicy: restartPolicy,
+        Memory: config.resources.memoryMb * 1024 * 1024,
+        CpuShares: Math.round(config.resources.cpuCores * 1024),
+        // Publish on the LOOPBACK interface only — the edge (host process, or a
+        // host-net OpenResty container) reaches it at 127.0.0.1:<hostPort>, and
+        // it never faces the network. Binding 0.0.0.0 here would expose every
+        // app directly, bypassing the edge's SSL/rate-limit/rules (and Docker's
+        // iptables bypass ufw). A pinned `config.hostPort` (loopback-port route
+        // strategy) is stable across redeploys; otherwise a random loopback port.
+        PortBindings: {
+          [`${config.port}/tcp`]: [
+            { HostIp: "127.0.0.1", HostPort: config.hostPort ? String(config.hostPort) : "" }
+          ]
+        }
+      }
+    });
+    await container.start();
+    log({
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      message: `Container ${container.id.slice(0, 12)} started.
+`,
+      level: "info"
+    });
+    return {
+      deploymentId: config.deploymentId,
+      containerId: container.id,
+      status: "running"
+    };
+  }
+  async stop(containerId) {
+    const container = this.docker.getContainer(containerId);
+    await container.stop();
+  }
+  async start(containerId) {
+    const container = this.docker.getContainer(containerId);
+    await container.start();
+  }
+  async restart(containerId) {
+    const container = this.docker.getContainer(containerId);
+    await container.restart();
+  }
+  async removeImage(imageRef) {
+    const image = this.docker.getImage(imageRef);
+    try {
+      await image.remove({ force: true });
+    } catch (err) {
+      if (!isDockerNotFoundError(err)) throw err;
+    }
+  }
+  async destroy(containerId) {
+    if (containerId.startsWith("/")) {
+      const executor = this.transport.kind === "ssh" ? this.connectionOptions?.executor : null;
+      if (executor) {
+        await executor.exec(`rm -rf ${sq(containerId)}`).catch(() => {
+        });
+      } else {
+        const { rm } = await import("fs/promises");
+        await rm(containerId, { recursive: true, force: true }).catch(() => {
+        });
+      }
+      return;
+    }
+    const container = this.docker.getContainer(containerId);
+    try {
+      await container.remove({ force: true });
+    } catch (err) {
+      if (!isDockerNotFoundError(err)) throw err;
+    }
+  }
+  /**
+   * Every container (running OR stopped) labeled for this project. Lets
+   * project teardown reclaim orphans that have no DB row — e.g. a deploy
+   * that started a container then failed during routing, or rows lost to
+   * a crash. The `openship.project` label is stamped at create time
+   * (see `labels()`), so this is authoritative for THIS docker host.
+   */
+  async listProjectContainerIds(projectId) {
+    const containers = await this.docker.listContainers({
+      all: true,
+      filters: { label: [`openship.project=${projectId}`] }
+    });
+    return containers.map((c) => c.Id);
+  }
+  /**
+   * Built images that belong to this project — the label `openship.project=<id>`
+   * that `labels()` stamps on every FINAL build image. Base/third-party images
+   * (postgres, redis, …) are PULLED, never labeled, so they can never appear
+   * here — that label filter is the primary guardrail for the image GC, which
+   * reconciles this on-host set against the DB keep-set. Includes untagged
+   * (dangling) superseded finals: labels persist after the tag is removed.
+   */
+  async listProjectImages(projectId) {
+    const images = await this.docker.listImages({
+      filters: { label: [`openship.project=${projectId}`] }
+    });
+    return images.map((img) => ({
+      id: img.Id,
+      repoTags: (img.RepoTags ?? []).filter((t) => t && t !== "<none>:<none>"),
+      buildId: img.Labels?.["openship.build"],
+      deploymentId: img.Labels?.["openship.deployment"],
+      size: img.Size ?? 0
+    }));
+  }
+  /**
+   * Reclaim dangling (untagged) images carrying THIS project's label — the
+   * superseded final-stage layers a rebuild leaves behind. NEVER a bare
+   * `docker image prune`: the label filter guarantees base/other-project/other-
+   * tool dangling layers are untouched. (Unlabeled multi-stage intermediate
+   * layers under the classic builder aren't caught — BuildKit avoids them.)
+   */
+  async pruneProjectDanglingImages(projectId) {
+    try {
+      await this.docker.pruneImages({
+        filters: { dangling: ["true"], label: [`openship.project=${projectId}`] }
+      });
+    } catch {
+    }
+  }
+  /**
+   * Containers labeled for this deployment, with live state — the reconcile
+   * read-back. `State` is dockerode's `running | exited | paused | ...`; map it
+   * to ContainerStatus the same way getContainerInfo does. Absence is conveyed
+   * by an EMPTY list (no container carries the label), which the reconciler
+   * reads as drift for the expected services.
+   */
+  async listDeploymentContainers(deploymentId) {
+    const containers = await this.docker.listContainers({
+      all: true,
+      filters: { label: [`openship.deployment=${deploymentId}`] }
+    });
+    const stateMap = {
+      running: "running",
+      healthy: "running",
+      starting: "running",
+      restarting: "running",
+      exited: "stopped",
+      paused: "stopped",
+      created: "stopped",
+      dead: "failed",
+      unhealthy: "failed"
+    };
+    return containers.map((c) => ({
+      containerId: c.Id,
+      status: stateMap[(c.State ?? "").toLowerCase().trim()] ?? "stopped",
+      serviceName: c.Labels?.["openship.service"]
+    }));
+  }
+  // ── Rollback primitives ──────────────────────────────────────────────
+  //
+  // Docker semantics:
+  //   makeActive — prefer `start` of the retained container (fast,
+  //     preserves PID/state). If the container was GC'd but the image
+  //     is still tagged, `run` from imageRef to provision a fresh
+  //     container. Stop the previous active as part of the swap.
+  //   archive   — `docker stop`. Image stays tagged. Container kept
+  //     for fast restart on later makeActive.
+  //   purge     — `docker rm` (force) + `docker rmi`. Past this point
+  //     rollback to this deployment is impossible.
+  async makeActive(input) {
+    if (input.from?.containerId) {
+      try {
+        await this.stop(input.from.containerId);
+      } catch {
+      }
+    }
+    if (input.to.containerId) {
+      try {
+        await this.start(input.to.containerId);
+        return { containerId: input.to.containerId };
+      } catch {
+      }
+    }
+    if (!input.to.imageRef) {
+      throw new Error(
+        `Cannot make deployment ${input.to.id} active: container is gone and no imageRef is stored. Artifact has been purged.`
+      );
+    }
+    const container = await this.docker.createContainer({
+      Image: input.to.imageRef,
+      name: `dep-${input.to.id}`,
+      HostConfig: { RestartPolicy: { Name: "unless-stopped" } }
+    });
+    await container.start();
+    return { containerId: container.id };
+  }
+  async archive(deployment) {
+    if (!deployment.containerId) return;
+    try {
+      await this.stop(deployment.containerId);
+    } catch {
+    }
+  }
+  async purge(deployment) {
+    if (deployment.containerId) {
+      try {
+        await this.destroy(deployment.containerId);
+      } catch {
+      }
+    }
+    if (deployment.imageRef) {
+      try {
+        await this.removeImage(deployment.imageRef);
+      } catch {
+      }
+    }
+  }
+  /**
+   * Inspect a container and return the names of its **named** volumes -
+   * the ones that survive `container.remove()` and would otherwise leak.
+   * Anonymous volumes are auto-removed with `{ v: true }` and don't need to
+   * be enumerated. Bind mounts and tmpfs are skipped (the user manages them
+   * outside our control). Returns [] if the container is already gone.
+   */
+  async inspectNamedVolumes(containerId) {
+    try {
+      const container = this.docker.getContainer(containerId);
+      const data = await container.inspect();
+      const mounts = data.Mounts ?? [];
+      return mounts.filter((m) => m.Type === "volume" && typeof m.Name === "string" && m.Name.length > 0).map((m) => m.Name);
+    } catch {
+      return [];
+    }
+  }
+  /** Remove a named volume by name. Best-effort - already-gone is fine. */
+  async removeVolume(name) {
+    try {
+      const volume = this.docker.getVolume(name);
+      await volume.remove({ force: true });
+    } catch {
+    }
+  }
+  // ── Docker discovery (label-agnostic) ────────────────────────────────────
+  //
+  // Enumerate the ENTIRE daemon, not just openship-labeled resources. Powers
+  // "migrate an existing Docker deployment": read whatever already runs on a
+  // server (a compose stack or hand-run containers) so it can be adopted as an
+  // Openship project. Strictly read-only.
+  /** Every container on the host (running or stopped), summarized. */
+  async listAllContainers() {
+    const containers = await this.docker.listContainers({ all: true });
+    return containers.map((c) => {
+      const labels = c.Labels ?? {};
+      const ip = firstNetworkIp(c.NetworkSettings?.Networks);
+      return {
+        id: c.Id,
+        names: (c.Names ?? []).map((n) => n.replace(/^\//, "")),
+        image: c.Image,
+        imageId: c.ImageID,
+        state: (c.State ?? "").toLowerCase().trim(),
+        status: c.Status,
+        labels,
+        ports: (c.Ports ?? []).map((p) => ({
+          privatePort: p.PrivatePort,
+          ...p.PublicPort ? { publicPort: p.PublicPort } : {},
+          type: p.Type ?? "tcp",
+          ...p.IP ? { ip: p.IP } : {}
+        })),
+        mounts: (c.Mounts ?? []).map(normalizeDockerMount),
+        ...ip ? { ip } : {},
+        composeProject: labels["com.docker.compose.project"] || void 0,
+        composeService: labels["com.docker.compose.service"] || void 0
+      };
+    });
+  }
+  /** Full inspect of one container, normalized. Null if the container is gone. */
+  async inspectContainer(id) {
+    let data;
+    try {
+      data = await this.docker.getContainer(id).inspect();
+    } catch (err) {
+      if (isDockerNotFoundError(err)) return null;
+      throw err;
+    }
+    const labels = data.Config?.Labels ?? {};
+    const hc = data.Config?.Healthcheck;
+    const rp = data.HostConfig?.RestartPolicy;
+    const configFiles = labels["com.docker.compose.project.config_files"];
+    return {
+      id: data.Id,
+      name: (data.Name ?? "").replace(/^\//, ""),
+      image: data.Config?.Image ?? data.Image,
+      imageId: data.Image,
+      state: (data.State?.Status ?? "").toLowerCase().trim() || "unknown",
+      command: toStringArray(data.Config?.Cmd),
+      entrypoint: toStringArray(data.Config?.Entrypoint),
+      env: data.Config?.Env ?? [],
+      workingDir: data.Config?.WorkingDir || void 0,
+      labels,
+      restart: rp?.Name ? { name: rp.Name, maximumRetryCount: rp.MaximumRetryCount } : void 0,
+      networks: Object.keys(data.NetworkSettings?.Networks ?? {}),
+      mounts: (data.Mounts ?? []).map(normalizeDockerMount),
+      ports: normalizeInspectPorts(data),
+      healthcheck: hc ? {
+        test: hc.Test,
+        interval: hc.Interval,
+        timeout: hc.Timeout,
+        retries: hc.Retries,
+        startPeriod: hc.StartPeriod
+      } : void 0,
+      composeProject: labels["com.docker.compose.project"] || void 0,
+      composeService: labels["com.docker.compose.service"] || void 0,
+      composeConfigFiles: configFiles ? configFiles.split(",").map((s) => s.trim()).filter(Boolean) : void 0,
+      composeWorkingDir: labels["com.docker.compose.project.working_dir"] || void 0
+    };
+  }
+  /** The image's baked-in default env (Config.Env). Discovery subtracts these
+   *  from a container's env so only user-set vars are imported, not the dozen
+   *  defaults a base image (postgres, node, …) ships with. [] if unavailable. */
+  async inspectImageEnv(ref) {
+    try {
+      const data = await this.docker.getImage(ref).inspect();
+      return data.Config?.Env ?? [];
+    } catch {
+      return [];
+    }
+  }
+  /** The image's baked-in default CMD (exec-form tokens). Used by migration to
+   *  drop a container's `command` when it merely restates the image default —
+   *  re-specifying it (and wrapping in `sh -c`) defeats entrypoints that drop
+   *  privileges by argv (postgres refuses to run as root otherwise). */
+  async inspectImageCmd(ref) {
+    try {
+      const data = await this.docker.getImage(ref).inspect();
+      return data.Config?.Cmd ?? [];
+    } catch {
+      return [];
+    }
+  }
+  /**
+   * Ensure an image is present, pulling it if missing. THE single image-pull
+   * path — reused by the deploy pipeline and the backup/migration executor so
+   * connectivity lives in one place.
+   *
+   * Over an SSH transport the pull runs as a blocking `docker pull` through the
+   * command executor, NOT dockerode's `pull` + `modem.followProgress`: the
+   * progress stream tunneled over the SSH docker socket never emits `end`, so
+   * followProgress hangs forever (this was the cross-server migration stall).
+   * A local socket has no such issue, so it keeps the native dockerode pull.
+   */
+  async pullImage(ref, opts) {
+    if (!opts?.force) {
+      try {
+        await this.docker.getImage(ref).inspect();
+        return;
+      } catch {
+      }
+    }
+    const executor = this.connectionOptions?.executor;
+    if (executor) {
+      await executor.exec(`docker pull ${sq(ref)}`, { timeout: 10 * 6e4 });
+      return;
+    }
+    const stream = await this.docker.pull(ref);
+    await new Promise((resolve, reject) => {
+      this.docker.modem.followProgress(stream, (err) => err ? reject(err) : resolve());
+    });
+  }
+  /** Is this image tag present on THIS daemon? Distinguishes a locally-built
+   *  image (must be transferred cross-server) from a registry tag (the target
+   *  just pulls it). */
+  async imageExistsLocally(ref) {
+    const executor = this.transport.kind === "ssh" ? this.connectionOptions?.executor : null;
+    if (executor) {
+      const out = await executor.exec(`docker image inspect ${sq(ref)} >/dev/null 2>&1 && echo yes || true`).catch(() => "");
+      return out.trim() === "yes";
+    }
+    try {
+      await this.docker.getImage(ref).inspect();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Stream `docker save <ref>` OUT of this daemon as a Readable — the source
+   * half of a cross-server image move. No extra compression: image layers are
+   * already gzip-compressed, so re-compressing burns CPU for ~nothing.
+   *
+   * Over SSH the save runs as a native `docker save` through the raw command
+   * channel (rawExec) — the same reason pullImage/build avoid dockerode over the
+   * tunnel: a streamed dockerode body over the streamlocal bridge is unreliable.
+   * Local socket / TCP use dockerode's image.get() directly.
+   */
+  async saveImage(ref) {
+    const executor = this.transport.kind === "ssh" ? this.connectionOptions?.executor : null;
+    if (executor?.rawExec) {
+      const { stdout: stdout2, stderr, onClose } = await executor.rawExec(`docker save ${sq(ref)}`);
+      let stderrBuf = "";
+      stderr.on("data", (c) => {
+        stderrBuf += c.toString();
+        if (stderrBuf.length > 16 * 1024) stderrBuf = stderrBuf.slice(-16 * 1024);
+      });
+      stderr.resume();
+      return { stdout: stdout2, awaitExit: onClose.then((code) => ({ code, stderr: stderrBuf.trim() })) };
+    }
+    const stdout = await this.docker.getImage(ref).get();
+    const awaitExit = new Promise((resolve, reject) => {
+      stdout.on("end", () => resolve({ code: 0, stderr: "" }));
+      stdout.on("error", reject);
+    });
+    return { stdout, awaitExit };
+  }
+  /**
+   * Load an image tar (a `docker save` stream) INTO this daemon — the target
+   * half of a cross-server image move. Over SSH the tar streams into a native
+   * `docker load` stdin (execWithInput); local socket / TCP use dockerode's
+   * loadImage. Throws on a non-zero load. Returns the reference `docker load`
+   * reported ("Loaded image( ID)?: <ref>") so the caller can retag: a
+   * save-by-id load is untagged AND restores under the CONFIG image id, which
+   * differs from the source ref — tagging by the source id would fail.
+   */
+  async loadImage(body) {
+    const executor = this.transport.kind === "ssh" ? this.connectionOptions?.executor : null;
+    if (executor?.execWithInput) {
+      const { code, stderr, stdout } = await executor.execWithInput(`docker load`, body);
+      if (code !== 0) throw new Error(`docker load exited ${code}${stderr ? `: ${stderr.slice(0, 500)}` : ""}`);
+      return parseLoadedImageRef(stdout);
+    }
+    const stream = await this.docker.loadImage(body);
+    let loadOutput = "";
+    await new Promise((resolve, reject) => {
+      this.docker.modem.followProgress(
+        stream,
+        (err) => err ? reject(err) : resolve(),
+        (ev) => {
+          if (ev?.stream) loadOutput += ev.stream;
+        }
+      );
+    });
+    return parseLoadedImageRef(loadOutput);
+  }
+  /**
+   * Apply a tag to an image (`docker tag <source> <target>`). Used after a
+   * save-by-ID / load: `docker save <id>` loads UNTAGGED, so the target daemon
+   * needs the original tag re-applied — the adopted service's deploy `imageRef`
+   * is that tag. `source` is typically the sha id, `target` the tag. Idempotent.
+   */
+  async tagImage(source, target) {
+    if (source === target) return;
+    const executor = this.transport.kind === "ssh" ? this.connectionOptions?.executor : null;
+    if (executor) {
+      await executor.exec(`docker tag ${sq(source)} ${sq(target)}`);
+      return;
+    }
+    const [repo, tag] = target.includes(":") ? [target.slice(0, target.lastIndexOf(":")), target.slice(target.lastIndexOf(":") + 1)] : [target, void 0];
+    await this.docker.getImage(source).tag({ repo, ...tag ? { tag } : {} });
+  }
+  /** Every named volume on the host. */
+  async listAllVolumes() {
+    const res = await this.docker.listVolumes();
+    return (res?.Volumes ?? []).map((v) => ({
+      name: v.Name,
+      driver: v.Driver,
+      mountpoint: v.Mountpoint,
+      labels: v.Labels ?? {},
+      composeProject: v.Labels?.["com.docker.compose.project"] || void 0
+    }));
+  }
+  /** Every network on the host. */
+  async listAllNetworks() {
+    const nets = await this.docker.listNetworks();
+    return nets.map((n) => ({
+      id: n.Id,
+      name: n.Name,
+      driver: n.Driver,
+      labels: n.Labels ?? {},
+      composeProject: n.Labels?.["com.docker.compose.project"] || void 0
+    }));
+  }
+  // ── Observability ──────────────────────────────────────────────────────
+  async getContainerInfo(containerId) {
+    const container = this.docker.getContainer(containerId);
+    let data;
+    try {
+      data = await container.inspect();
+    } catch (err) {
+      if (isDockerNotFoundError(err)) {
+        return { containerId, status: "missing" };
+      }
+      throw err;
+    }
+    const statusMap = {
+      running: "running",
+      healthy: "running",
+      starting: "running",
+      restarting: "running",
+      exited: "stopped",
+      paused: "stopped",
+      created: "stopped",
+      dead: "failed",
+      unhealthy: "failed"
+    };
+    const startedAt = data.State.StartedAt;
+    const uptimeSeconds = startedAt && data.State.Running ? Math.floor((Date.now() - new Date(startedAt).getTime()) / 1e3) : void 0;
+    const { ip, hostPort } = extractNetworkInfo(data);
+    let status;
+    if (data.State.Running) {
+      status = "running";
+    } else if (data.State.Paused) {
+      status = "stopped";
+    } else {
+      const rawStatus = (data.State.Status ?? "").toLowerCase().trim();
+      status = statusMap[rawStatus] ?? "stopped";
+    }
+    return {
+      containerId,
+      status,
+      ip,
+      hostPort,
+      uptimeSeconds: uptimeSeconds && uptimeSeconds > 0 ? uptimeSeconds : void 0
+    };
+  }
+  async getRuntimeLogs(containerId, tail) {
+    const container = this.docker.getContainer(containerId);
+    const buffer = await container.logs({
+      stdout: true,
+      stderr: true,
+      timestamps: true,
+      tail: tail ?? 200
+    });
+    const raw = stripDockerHeaders(buffer);
+    return raw.split("\n").filter(Boolean).map((line) => {
+      const { timestamp, message } = parseTimestampedLine(line);
+      return { timestamp, message, level: parseLogLevel(message) };
+    });
+  }
+  async streamRuntimeLogs(containerId, onLog, opts) {
+    const container = this.docker.getContainer(containerId);
+    const stream = await container.logs({
+      stdout: true,
+      stderr: true,
+      timestamps: true,
+      follow: true,
+      tail: opts?.tail ?? 100
+    });
+    let destroyed = false;
+    let buffer = "";
+    stream.on("data", (chunk) => {
+      if (destroyed) return;
+      buffer += stripDockerChunkHeader(chunk).toString("utf-8");
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+      for (const line of lines) {
+        if (!line) continue;
+        const { timestamp, message } = parseTimestampedLine(line);
+        onLog({ timestamp, message, level: parseLogLevel(message) });
+      }
+    });
+    stream.on("end", () => {
+      if (buffer && !destroyed) {
+        onLog({ timestamp: (/* @__PURE__ */ new Date()).toISOString(), message: buffer, level: parseLogLevel(buffer) });
+        buffer = "";
+      }
+    });
+    return () => {
+      if (!destroyed) {
+        destroyed = true;
+        stream.destroy?.();
+      }
+    };
+  }
+  async getUsage(containerId) {
+    const container = this.docker.getContainer(containerId);
+    const stats = await container.stats({ stream: false });
+    const cpuDelta = stats.cpu_stats.cpu_usage.total_usage - stats.precpu_stats.cpu_usage.total_usage;
+    const systemDelta = stats.cpu_stats.system_cpu_usage - stats.precpu_stats.system_cpu_usage;
+    const numCpus = stats.cpu_stats.online_cpus || 1;
+    const cpuPercent = systemDelta > 0 ? cpuDelta / systemDelta * numCpus * 100 : 0;
+    const memoryMb = (stats.memory_stats.usage ?? 0) / (1024 * 1024);
+    let networkRxBytes = 0;
+    let networkTxBytes = 0;
+    if (stats.networks) {
+      for (const iface of Object.values(stats.networks)) {
+        networkRxBytes += iface.rx_bytes ?? 0;
+        networkTxBytes += iface.tx_bytes ?? 0;
+      }
+    }
+    let diskBytes = 0;
+    if (stats.blkio_stats?.io_service_bytes_recursive) {
+      for (const entry of stats.blkio_stats.io_service_bytes_recursive) {
+        diskBytes += entry.value ?? 0;
+      }
+    }
+    const diskMb = diskBytes / (1024 * 1024);
+    return {
+      cpuPercent: Math.round(cpuPercent * 100) / 100,
+      memoryMb: Math.round(memoryMb * 100) / 100,
+      diskMb: Math.round(diskMb * 100) / 100,
+      networkRxBytes,
+      networkTxBytes
+    };
+  }
+  // ── Network ────────────────────────────────────────────────────────────
+  async getContainerIp(containerId) {
+    const container = this.docker.getContainer(containerId);
+    const data = await container.inspect();
+    for (const net2 of Object.values(data.NetworkSettings.Networks ?? {})) {
+      if (net2.IPAddress) return net2.IPAddress;
+    }
+    return null;
+  }
+  /**
+   * Open an interactive PTY shell inside a deployed container. Powers
+   * the in-dashboard service terminal — see apps/api/src/modules/service-terminal/.
+   *
+   * Wire-up: dockerode's `container.exec({Tty: true, AttachStdin: true,
+   * AttachStdout: true, AttachStderr: true})` returns an Exec handle.
+   * Starting it with `{hijack: true, stdin: true}` gives a single bi-
+   * directional Duplex carrying TTY bytes in both directions (when Tty
+   * is true, stderr is merged into stdout — exactly what xterm expects).
+   *
+   * The returned ShellSession matches SshExecutor.openShell so the
+   * websocket bridge in service-terminal.controller.ts is identical
+   * across Docker + Cloud + SSH callers.
+   */
+  async openServiceShell(containerId, opts) {
+    const container = this.docker.getContainer(containerId);
+    const cols = clampShellWindow(opts?.cols, 80, 1, 1e3);
+    const rows = clampShellWindow(opts?.rows, 24, 1, 500);
+    const term = opts?.term || "xterm-256color";
+    const inspect = await container.inspect().catch(() => null);
+    if (!inspect?.State.Running) {
+      throw new Error(
+        `Container ${containerId} is not running (status: ${inspect?.State.Status ?? "unknown"})`
+      );
+    }
+    const exec = await container.exec({
+      AttachStdin: true,
+      AttachStdout: true,
+      AttachStderr: true,
+      Tty: true,
+      Cmd: ["/bin/sh", "-lc", "exec $(command -v bash || echo /bin/sh)"],
+      Env: [`TERM=${term}`]
+    });
+    const duplex = await exec.start({
+      hijack: true,
+      stdin: true,
+      Tty: true
+    });
+    try {
+      await exec.resize({ h: rows, w: cols });
+    } catch {
+    }
+    const stdout = new PassThrough();
+    const stderr = new PassThrough();
+    duplex.on("data", (chunk) => stdout.write(chunk));
+    duplex.on("end", () => {
+      stdout.end();
+      stderr.end();
+    });
+    duplex.on("error", () => {
+      stdout.end();
+      stderr.end();
+    });
+    const stdin = new Writable({
+      write(chunk, _enc, cb) {
+        duplex.write(chunk, (err) => cb(err ?? void 0));
+      },
+      final(cb) {
+        try {
+          duplex.end();
+        } catch {
+        }
+        cb();
+      }
+    });
+    const closeListeners = [];
+    let closed = false;
+    const fireClose = (code, signal) => {
+      if (closed) return;
+      closed = true;
+      for (const cb of closeListeners) {
+        try {
+          cb(code, signal);
+        } catch {
+        }
+      }
+    };
+    duplex.on("close", () => {
+      exec.inspect().then((info) => fireClose(info.ExitCode ?? null)).catch(() => fireClose(null));
+    });
+    return {
+      stdin,
+      stdout,
+      stderr,
+      setWindow: (c, r) => {
+        const sc = clampShellWindow(c, 80, 1, 1e3);
+        const sr = clampShellWindow(r, 24, 1, 500);
+        void exec.resize({ h: sr, w: sc }).catch(() => void 0);
+      },
+      close: (_signal) => {
+        try {
+          duplex.end();
+        } catch {
+        }
+        try {
+          duplex.destroy();
+        } catch {
+        }
+      },
+      onClose: (cb) => {
+        closeListeners.push(cb);
+      }
+    };
+  }
+  /**
+   * Non-interactive one-shot exec INSIDE a container (Tty:false ⇒ dockerode
+   * multiplexes stdout/stderr, so demux the frames). Sibling of
+   * `openServiceShell` for the advisory port probe — reads stdout + the exit
+   * code. Runs in the CONTAINER, not on the daemon host (never use
+   * `this.executor` here).
+   */
+  async execInContainer(containerId, command) {
+    const container = this.docker.getContainer(containerId);
+    const inspect = await container.inspect().catch(() => null);
+    if (!inspect?.State.Running) {
+      throw new Error(
+        `Container ${containerId} is not running (status: ${inspect?.State.Status ?? "unknown"})`
+      );
+    }
+    const exec = await container.exec({
+      AttachStdout: true,
+      AttachStderr: true,
+      Tty: false,
+      Cmd: ["sh", "-c", command]
+    });
+    const stream = await exec.start({ hijack: true, stdin: false });
+    const stdoutChunks = [];
+    const stdoutSink = new Writable({
+      write(chunk, _enc, cb) {
+        stdoutChunks.push(Buffer.from(chunk));
+        cb();
+      }
+    });
+    const stderrSink = new Writable({
+      write(_chunk, _enc, cb) {
+        cb();
+      }
+    });
+    this.docker.modem.demuxStream(stream, stdoutSink, stderrSink);
+    await new Promise((resolve, reject) => {
+      stream.on("end", resolve);
+      stream.on("close", resolve);
+      stream.on("error", reject);
+    });
+    const info = await exec.inspect().catch(() => null);
+    return {
+      exitCode: info?.ExitCode ?? null,
+      stdout: Buffer.concat(stdoutChunks).toString("utf8")
+    };
+  }
+  /** Command runner scoped to the inside of the container (advisory port probe). */
+  async inContainerExecutor(containerId) {
+    return {
+      exec: async (command) => {
+        const { exitCode, stdout } = await this.execInContainer(containerId, command);
+        if (exitCode && exitCode !== 0) {
+          throw new Error(stdout || `exec exited with code ${exitCode}`);
+        }
+        return stdout;
+      }
+    };
+  }
+  // ── Compose / multi-service ────────────────────────────────────────────
+  /**
+   * Ensure a project-level Docker network exists.
+   * All services in a compose project share this network and can
+   * reach each other by service name as hostname.
+   */
+  async ensureNetwork(slug) {
+    const networkName = `openship-${slug}`;
+    const critical = async () => {
+      const networks = await this.docker.listNetworks({
+        filters: { name: [networkName] }
+      });
+      const existing = networks.find((n) => n.Name === networkName);
+      if (existing) return existing.Id;
+      const network = await this.docker.createNetwork({
+        Name: networkName,
+        Driver: "bridge",
+        Labels: { "openship.network": slug }
+      });
+      return network.id;
+    };
+    return this.provisionLock ? this.provisionLock.run(critical) : critical();
+  }
+  async ensureServiceGroup(config) {
+    void config.deploymentId;
+    const networkId = await this.ensureNetwork(config.slug);
+    await this.reconcileNetworkMembership(networkId, config.projectId);
+    return { id: networkId };
+  }
+  /**
+   * Join already-running containers (migration attach-live reuse) to a project's
+   * `openship-<slug>` network with a DNS alias each — so a natively-deployed
+   * service in the SAME project resolves them by name (e.g. a freshly-built `web`
+   * reaching the reused `postgres:5432`). These containers keep their ORIGINAL
+   * openship labels, so the label-scoped reconcileNetworkMembership never joins
+   * them; this is the explicit, additive join (a network connect does NOT restart
+   * the container or touch its volumes). Idempotent + best-effort per member.
+   */
+  async joinServiceGroupContainers(slug, members) {
+    if (members.length === 0) return;
+    const networkId = await this.ensureNetwork(slug);
+    const network = this.docker.getNetwork(networkId);
+    for (const m of members) {
+      if (!m.containerId) continue;
+      try {
+        await network.connect({
+          Container: m.containerId,
+          EndpointConfig: m.alias ? { Aliases: [m.alias] } : {}
+        });
+      } catch (err) {
+        const msg = err?.message ?? "";
+        if (!/already exists|already connected/i.test(msg)) {
+          console.warn(
+            `[docker] group join failed for ${m.containerId.slice(0, 12)} (${m.alias}): ${msg}`
+          );
+        }
+      }
+    }
+  }
+  /**
+   * Guard for GRANDFATHERED (non-namespaced) services: a bare named volume that
+   * another project's container already mounts is a cross-project collision —
+   * the exact bug (two projects sharing one postgres volume) this change
+   * prevents for new services. New namespaced services can't hit this (their
+   * volume name is project-unique by construction).
+   *
+   * Only a FRESH claim is blocked: if THIS project already mounts the name
+   * (it's the incumbent) a redeploy is never blocked — otherwise, during an
+   * active collision, whichever owner redeployed first would be locked out of
+   * its own release. Best-effort on the list call; throws ONLY on a real
+   * newcomer collision so the operator renames it.
+   */
+  async assertNoForeignNamedVolumeCollision(config) {
+    const named = /* @__PURE__ */ new Set();
+    for (const spec of config.volumes) {
+      const body = spec.replace(/:(ro|rw|z|Z|nocopy)$/, "");
+      const parts = body.split(":");
+      if (parts.length < 2) continue;
+      const source = parts[0];
+      if (isHostPathSource(source)) continue;
+      named.add(source);
+    }
+    if (named.size === 0) return;
+    let containers;
+    try {
+      containers = await this.docker.listContainers({ all: true });
+    } catch {
+      return;
+    }
+    const ownNames = /* @__PURE__ */ new Set();
+    const foreign = /* @__PURE__ */ new Map();
+    for (const c of containers) {
+      const owner = c.Labels?.["openship.project"];
+      if (!owner) continue;
+      for (const m of c.Mounts ?? []) {
+        if (m.Type !== "volume" || !m.Name || !named.has(m.Name)) continue;
+        if (owner === config.projectId) ownNames.add(m.Name);
+        else if (!foreign.has(m.Name)) foreign.set(m.Name, c.Names?.[0]?.replace(/^\//, "") ?? owner);
+      }
+    }
+    for (const [name, other] of foreign) {
+      if (ownNames.has(name)) continue;
+      throw new Error(
+        `Volume "${name}" is already used by another project's container "${other}". Rename this service's volume to a project-unique name before deploying, to avoid overwriting the other project's data.`
+      );
+    }
+  }
+  /**
+   * Ensure every container belonging to this project is attached to
+   * `networkId` with its service-name alias. Idempotent (already-connected is a
+   * no-op) and best-effort (never throws). Normal/partial/smart redeploys don't
+   * strand containers (the network is reused by name → stable id); this heals
+   * the narrow case where the network's identity changed out-of-band (docker
+   * network prune/rm, daemon/host rebuild) and surviving containers fell off it.
+   */
+  async reconcileNetworkMembership(networkId, projectId) {
+    let containers;
+    try {
+      containers = await this.docker.listContainers({
+        all: true,
+        filters: { label: [`openship.project=${projectId}`] }
+      });
+    } catch {
+      return;
+    }
+    const network = this.docker.getNetwork(networkId);
+    for (const c of containers) {
+      const onNetwork = Object.values(c.NetworkSettings?.Networks ?? {}).some(
+        (n) => n?.NetworkID === networkId
+      );
+      if (onNetwork) continue;
+      const service = c.Labels?.["openship.service"];
+      try {
+        await network.connect({
+          Container: c.Id,
+          EndpointConfig: service ? { Aliases: [service] } : {}
+        });
+      } catch (err) {
+        const msg = err?.message ?? "";
+        if (!/already exists|already connected/i.test(msg)) {
+          console.warn(
+            `[docker] reconcile connect failed for ${c.Id.slice(0, 12)} \u2192 ${networkId.slice(0, 12)}: ${msg}`
+          );
+        }
+      }
+    }
+  }
+  /**
+   * Attach every container of `projectId` to the given networks (by name) — for
+   * cross-project service links: a consumer joins a linked database app's
+   * `openship-<slug>` network so it resolves that app's service alias
+   * (`mongo:27017`) with no public port. Best-effort + idempotent; a network that
+   * doesn't exist (source not deployed) is skipped and nothing here ever throws —
+   * a link networking failure must never fail the consumer's deploy.
+   */
+  async attachToExternalNetworks(projectId, networkNames) {
+    if (networkNames.length === 0) return;
+    let containers;
+    try {
+      containers = await this.docker.listContainers({
+        all: true,
+        filters: { label: [`openship.project=${projectId}`] }
+      });
+    } catch {
+      return;
+    }
+    for (const name of networkNames) {
+      const network = this.docker.getNetwork(name);
+      let netId;
+      try {
+        const info = await network.inspect();
+        netId = info.Id;
+      } catch {
+        continue;
+      }
+      for (const c of containers) {
+        const onNetwork = Object.values(c.NetworkSettings?.Networks ?? {}).some(
+          (n) => n?.NetworkID === netId
+        );
+        if (onNetwork) continue;
+        try {
+          await network.connect({ Container: c.Id });
+        } catch (err) {
+          const msg = err?.message ?? "";
+          if (!/already exists|already connected/i.test(msg)) {
+            console.warn(
+              `[docker] link-connect failed for ${c.Id.slice(0, 12)} \u2192 ${name}: ${msg}`
+            );
+          }
+        }
+      }
+    }
+  }
+  /** Remove a project network (best-effort). */
+  async removeNetwork(slug) {
+    const networkName = `openship-${slug}`;
+    try {
+      const network = this.docker.getNetwork(networkName);
+      await network.remove();
+    } catch {
+    }
+  }
+  /**
+   * Deploy a single service container on a project network.
+   * Unlike `deploy()` which binds to a random host port,
+   * service containers join the project network with their service name as hostname.
+   * External port bindings are only created for services that explicitly expose ports.
+   */
+  async deployServiceWorkload(group, config, onLog) {
+    const log = onLog ?? (() => {
+    });
+    const containerName = `openship-${config.slug}-${config.serviceName}`;
+    try {
+      const existing = this.docker.getContainer(containerName);
+      await existing.remove({ force: true });
+    } catch {
+    }
+    const env = [
+      ...config.publicPort && config.environment.PORT === void 0 ? [`PORT=${config.publicPort}`] : [],
+      ...Object.entries(config.environment).map(([k, v]) => `${k}=${v}`)
+    ];
+    const cmd = config.command ? ["sh", "-c", config.command] : void 0;
+    const { exposedPorts, portBindings } = parsePortBindings(config.ports);
+    if (!config.namespaceVolumes) {
+      await this.assertNoForeignNamedVolumeCollision(config);
+    }
+    const scopedBinds = scopeVolumeBinds(config.slug, config.volumes, config.namespaceVolumes);
+    const binds = scopedBinds.length > 0 ? scopedBinds : void 0;
+    const restartPolicy = resolveRestartPolicy(config.restart);
+    const healthcheck = toDockerHealthcheck(config.advanced?.healthcheck);
+    log({
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      message: `Creating service container ${containerName} from ${config.image}...
+`,
+      level: "info"
+    });
+    if (!config.image.startsWith("openship/")) {
+      try {
+        log({
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          message: `Pulling image ${config.image}...
+`,
+          level: "info"
+        });
+        await this.pullImage(config.image, { force: config.forcePull });
+      } catch (err) {
+        log({
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          message: `Failed to pull ${config.image}: ${err}
+`,
+          level: "error"
+        });
+        throw err;
+      }
+    }
+    const container = await this.docker.createContainer({
+      name: containerName,
+      Image: config.image,
+      Cmd: cmd,
+      Env: env,
+      Hostname: config.serviceName,
+      Labels: {
+        ...this.labels({
+          deploymentId: config.deploymentId,
+          projectId: config.projectId
+        }),
+        "openship.service": config.serviceName
+      },
+      ...healthcheck && { Healthcheck: healthcheck },
+      ExposedPorts: exposedPorts,
+      HostConfig: {
+        RestartPolicy: restartPolicy,
+        ...config.resources?.memoryMb && {
+          Memory: config.resources.memoryMb * 1024 * 1024
+        },
+        ...config.resources?.cpuCores && {
+          CpuShares: Math.round(config.resources.cpuCores * 1024)
+        },
+        PortBindings: portBindings,
+        Binds: binds,
+        NetworkMode: group.id
+      },
+      NetworkingConfig: {
+        EndpointsConfig: {
+          [group.id]: {
+            Aliases: [config.serviceName]
+          }
+        }
+      }
+    });
+    try {
+      await container.start();
+    } catch (startErr) {
+      try {
+        await container.remove({ force: true });
+      } catch {
+      }
+      throw startErr;
+    }
+    const data = await container.inspect();
+    const { ip, hostPort } = extractNetworkInfo(data);
+    const imageDigest = await this.resolveImageDigest(config.image).catch(() => void 0);
+    log({
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      message: `Service ${config.serviceName} started (${container.id.slice(0, 12)})${ip ? ` at ${ip}` : ""}.
+`,
+      level: "info"
+    });
+    return {
+      containerId: container.id,
+      status: "running",
+      ip,
+      hostPort,
+      imageDigest
+    };
+  }
+  /**
+   * Resolve the `repo@sha256:…` digest of a pulled image from its RepoDigests,
+   * preferring the entry whose repo matches `ref` (an image may carry digests
+   * for several repos). Returns undefined for a locally-built image (no
+   * RepoDigests) or any inspect error. Works local + SSH (plain inspect, no
+   * followProgress). Never throws.
+   */
+  async resolveImageDigest(ref) {
+    const info = await this.docker.getImage(ref).inspect();
+    const repoDigests = info?.RepoDigests ?? [];
+    if (repoDigests.length === 0) return void 0;
+    const noDigest = ref.split("@")[0];
+    const lastColon = noDigest.lastIndexOf(":");
+    const lastSlash = noDigest.lastIndexOf("/");
+    const repo = lastColon > lastSlash ? noDigest.slice(0, lastColon) : noDigest;
+    return repoDigests.find((d) => d.startsWith(`${repo}@`)) ?? repoDigests[0];
+  }
+  async deployService(config, onLog) {
+    return this.deployServiceWorkload({ id: config.networkId }, config, onLog);
+  }
+};
+
+export {
+  scopedVolumeName,
+  isHostPathSource,
+  DockerRuntime
+};