openship 0.6.6 → 0.6.8

package/dist/{chunk-77QDF6UD.js → chunk-3MP6ACKM.js}

@@ -3,24 +3,38 @@
 import { createRequire as __ospCreateRequire } from "node:module";
 const require = __ospCreateRequire(import.meta.url);
 import {
+  BuildKitTraceDecoder,
   createDockerBuildContext,
-  generateDockerfile,
+  missingContextDockerfileMessage,
   prepareSourceTree,
-  resolveDockerfileCandidates,
-  resolveServiceDockerfile,
-  staticBuilderOutputPath
-} from "./chunk-LUKYPVJ4.js";
+  resolveDockerBuildArgs,
+  resolveServiceDockerfile
+} from "./chunk-6GU6JSK6.js";
+import {
+  isArtifactPathRef,
+  removeManagedArtifact
+} from "./chunk-SK4FFCFR.js";
 import {
   BuildCancelledError,
   BuildLogger,
   assembleGitClone,
+  builderContextRoot,
+  dockerBuildContextDirectory,
+  droppedRuntimeEnvMessage,
+  generateDockerfile,
+  isExcludedDocRootEntry,
   killProcessesUnderDir,
   materializeGitSsh,
+  normalizeDockerRelativePath,
   parseLogLevel,
+  resolveContextDockerfileCandidates,
+  resolveDockerfileCandidates,
   shellGitSshWriter,
+  splitRuntimeEnv,
   sq,
+  staticBuilderOutputPath,
   transferLocalDirectory
-} from "./chunk-LH2PLRQO.js";
+} from "./chunk-AHJYP7DG.js";
 import {
   DOCKER_DIAL_STDIO_COMMAND,
   attachDialStdioDiagnostics,
@@ -29,23 +43,28 @@ import {
   execSshCommand,
   openDockerDialStdioChannel,
   openSshUnixSocket
-} from "./chunk-PCPVTH6M.js";
+} from "./chunk-TAZZZKYO.js";
 import {
   dirOf,
   ensureOwnedDir
-} from "./chunk-UVNMQM7W.js";
+} from "./chunk-NPSRGIHV.js";
+import {
+  OPENSHIP_LABEL
+} from "./chunk-D6HU4VUZ.js";
+import {
+  isRuntimeNotFoundError
+} from "./chunk-N5YZMO33.js";
 import {
   formatCpuCores,
   formatMemoryMb,
   hasCpuLimit,
   hasMemoryLimit,
-  isRuntimeNotFoundError,
   ownsNetworkEndpoint,
   registryConfigKeys,
   registryForImage,
   safeErrorMessage,
   withTimeout
-} from "./chunk-UJ6JZM65.js";
+} from "./chunk-WEZFTL4V.js";
 import {
   __commonJS,
   __require,
@@ -4609,6 +4628,7 @@ var tarFs = __toESM(require_tar_fs(), 1);
 import Dockerode from "dockerode";
 import { createGzip } from "zlib";
 import { PassThrough, Writable } from "stream";
+import { relative, sep } from "path";
 
 // ../../packages/adapters/src/runtime/docker-auth.ts
 import { readFile } from "fs/promises";
@@ -4712,6 +4732,10 @@ var MODE_SUFFIX = /:(ro|rw|z|Z|nocopy)$/;
 function scopedVolumeName(slug, name) {
   return `openship-${slug}-${name}`;
 }
+function ensureScopedVolumeName(slug, source) {
+  const prefix = `openship-${slug}-`;
+  return source.startsWith(prefix) ? source : scopedVolumeName(slug, source);
+}
 function isHostPathSource(source) {
   return source.startsWith("/") || source.startsWith("./") || source.startsWith("../") || source.startsWith("~");
 }
@@ -4931,7 +4955,6 @@ import { join as join2 } from "path";
 import net2 from "net";
 var DEFAULT_REMOTE_DOCKER_SOCKET_PATH = "/var/run/docker.sock";
 var resolvedDockerSocketPathCache = /* @__PURE__ */ new WeakMap();
-var STREAMLOCAL_PROBE_TIMEOUT_MS = 8e3;
 var STREAMLOCAL_DATA_VERIFY_TIMEOUT_MS = 3e3;
 var DIAL_STDIO_ANSWER_TIMEOUT_MS = 3e3;
 var VERIFY_BUFFER_CAP_BYTES = 8 * 1024 * 1024;
@@ -5257,12 +5280,12 @@ function createDockerSshBridge(opts) {
     try {
       probe = await withTimeout(
         openStreamlocalUpstream(opts),
-        STREAMLOCAL_PROBE_TIMEOUT_MS,
-        `streamlocal open timed out after ${STREAMLOCAL_PROBE_TIMEOUT_MS / 1e3}s`
+        STREAMLOCAL_DATA_VERIFY_TIMEOUT_MS,
+        `streamlocal open timed out after ${STREAMLOCAL_DATA_VERIFY_TIMEOUT_MS / 1e3}s`
       );
       const stream = probe;
       const flowed = await new Promise((resolve) => {
-        const timer = setTimeout(() => resolve(false), STREAMLOCAL_PROBE_TIMEOUT_MS);
+        const timer = setTimeout(() => resolve(false), STREAMLOCAL_DATA_VERIFY_TIMEOUT_MS);
         const settle = (ok) => {
           clearTimeout(timer);
           resolve(ok);
@@ -5512,7 +5535,7 @@ function resolveDockerTransport(opts) {
 // ../../packages/adapters/src/runtime/docker.ts
 var isDockerNotFoundError = isRuntimeNotFoundError;
 function ownsBuiltImage(imageRef) {
-  return imageRef.startsWith("openship/");
+  return /^openship\/[a-z0-9][a-z0-9._-]*:bld_[A-Za-z0-9_-]+$/.test(imageRef);
 }
 function clampShellWindow(value, fallback, min, max) {
   const n = Number.isFinite(value) ? Number(value) : fallback;
@@ -5580,14 +5603,7 @@ var IN_CONTAINER_EXEC_WATCHDOG = [
 ].join("\n");
 function buildInContainerExecCmd(command, timeoutMs) {
   const seconds = Math.max(1, Math.ceil(timeoutMs / 1e3));
-  return [
-    "sh",
-    "-c",
-    IN_CONTAINER_EXEC_WATCHDOG,
-    "openship-exec",
-    command,
-    String(seconds)
-  ];
+  return ["sh", "-c", IN_CONTAINER_EXEC_WATCHDOG, "openship-exec", command, String(seconds)];
 }
 async function resolveExecExitCode(exec, label) {
   let info = await exec.inspect();
@@ -5701,9 +5717,10 @@ function parsePortBindings(portSpecs) {
   }
   return { exposedPorts, portBindings };
 }
-function packBuildContext(contextDir, entries, cancelSignal) {
+function packBuildContext(contextDir, entries, cancelSignal, ignoreContextPath) {
   const controller = new AbortController();
-  const pack2 = tarFs.pack(contextDir, { entries });
+  const ignore = ignoreContextPath ? (absolutePath) => ignoreContextPath(relative(contextDir, absolutePath).split(sep).join("/")) : void 0;
+  const pack2 = tarFs.pack(contextDir, { entries, ignore });
   const body = pack2.pipe(createGzip());
   let contextError = null;
   const capture = (err) => {
@@ -5721,7 +5738,7 @@ function packBuildContext(contextDir, entries, cancelSignal) {
 var DURATION_UNITS_NS = {
   ns: 1,
   us: 1e3,
-  "\xB5s": 1e3,
+  \u00B5s: 1e3,
   ms: 1e6,
   s: 1e9,
   m: 6e10,
@@ -5829,20 +5846,45 @@ function firstNetworkIp(networks) {
 }
 function extractNetworkInfo(data) {
   let ip;
-  for (const net3 of Object.values(data.NetworkSettings.Networks ?? {})) {
+  for (const net3 of Object.values(data.NetworkSettings?.Networks ?? {})) {
     if (net3.IPAddress) {
       ip = net3.IPAddress;
       break;
     }
   }
+  const hostPortByContainerPort = {};
   let hostPort;
-  for (const bindings of Object.values(data.NetworkSettings.Ports ?? {})) {
-    if (bindings?.[0]?.HostPort) {
-      hostPort = parseInt(bindings[0].HostPort, 10);
-      break;
+  const liveBindings = data.NetworkSettings?.Ports ?? {};
+  const configuredBindings = data.HostConfig?.PortBindings ?? {};
+  for (const key of /* @__PURE__ */ new Set([...Object.keys(liveBindings), ...Object.keys(configuredBindings)])) {
+    const [containerRaw, protocol = "tcp"] = key.split("/");
+    if (protocol.toLowerCase() !== "tcp") continue;
+    const containerPort = Number(containerRaw);
+    if (!Number.isSafeInteger(containerPort) || containerPort < 1 || containerPort > 65535) {
+      continue;
+    }
+    const live = liveBindings[key];
+    const bindings = live && live.some((binding) => binding?.HostPort) ? live : configuredBindings[key];
+    const candidates = (bindings ?? []).map((binding, index) => {
+      const port = Number(binding?.HostPort);
+      if (!Number.isSafeInteger(port) || port < 1 || port > 65535) return null;
+      const ip2 = binding?.HostIp?.trim().replace(/^\[|\]$/g, "") ?? "";
+      const priority = ip2 === "127.0.0.1" || ip2 === "::1" ? 3 : /^127(?:\.\d{1,3}){3}$/.test(ip2) ? 2 : ip2 && ip2 !== "0.0.0.0" && ip2 !== "::" ? 1 : 0;
+      return { index, port, priority };
+    }).filter(
+      (candidate) => Boolean(candidate)
+    ).sort((left, right) => right.priority - left.priority || left.index - right.index);
+    const selected = candidates[0]?.port;
+    if (selected !== void 0) {
+      hostPortByContainerPort[containerPort] = selected;
+      hostPort ??= selected;
     }
   }
-  return { ip, hostPort };
+  return {
+    ip,
+    hostPort,
+    ...Object.keys(hostPortByContainerPort).length ? { hostPortByContainerPort } : {}
+  };
 }
 function parseLoadedImageRef(output) {
   const matches = [...(output || "").matchAll(/Loaded image(?: ID)?:\s*(\S+)/gi)];
@@ -5891,6 +5933,7 @@ var DockerRuntime = class _DockerRuntime {
   name = "docker";
   capabilities = /* @__PURE__ */ new Set([
     "build",
+    "prebuiltImage",
     "deploy",
     "multiServiceDeploy",
     "stop",
@@ -5999,11 +6042,11 @@ var DockerRuntime = class _DockerRuntime {
   /** Labels applied to both build images and deploy containers. */
   labels(config) {
     const l = {
-      "openship.project": config.projectId
+      [OPENSHIP_LABEL.project]: config.projectId
     };
-    if (config.deploymentId) l["openship.deployment"] = config.deploymentId;
-    if (config.sessionId) l["openship.build"] = config.sessionId;
-    if (config.service) l["openship.service"] = config.service;
+    if (config.deploymentId) l[OPENSHIP_LABEL.deployment] = config.deploymentId;
+    if (config.sessionId) l[OPENSHIP_LABEL.build] = config.sessionId;
+    if (config.service) l[OPENSHIP_LABEL.service] = config.service;
     return l;
   }
   // ── Build lifecycle ────────────────────────────────────────────────────
@@ -6045,12 +6088,20 @@ var DockerRuntime = class _DockerRuntime {
     logger.log(`[${step}] ${label} ${message}`);
     logger.step(step, status, message);
   }
-  handleBuildEvent(event, logger) {
+  handleBuildEvent(event, logger, trace) {
     const errorMessage = event.errorDetail?.message ?? event.error;
     if (errorMessage) {
       logger.log(errorMessage, "error");
       return errorMessage;
     }
+    if (event.id === "moby.buildkit.trace" && typeof event.aux === "string") {
+      let hint = null;
+      for (const line of trace?.push(event.aux) ?? []) {
+        logger.log(line.message, line.level === "error" ? "error" : parseLogLevel(line.message));
+        hint ??= this.extractBuildFailureHint(line.message);
+      }
+      return hint;
+    }
     if (event.stream) {
       const line = event.stream.trim();
       if (!line) return null;
@@ -6107,6 +6158,12 @@ var DockerRuntime = class _DockerRuntime {
     if (/returned a non-zero code:\s*\d+/i.test(line)) {
       return line;
     }
+    if (/requires? BuildKit|BuildKit is enabled but the buildx component/i.test(line)) {
+      return `${line} \u2014 this Dockerfile needs BuildKit. Install the docker buildx plugin on the build host (\`docker-buildx-plugin\`), or remove the BuildKit-only instruction.`;
+    }
+    if (/buildkit (is )?(not (supported|enabled)|disabled)|builder version.*not supported/i.test(line)) {
+      return `${line} \u2014 this Dockerfile needs BuildKit but this Docker daemon has it disabled. Enable it ("features": {"buildkit": true} in daemon.json) or remove the BuildKit-only instruction.`;
+    }
     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.";
     }
@@ -6158,26 +6215,69 @@ var DockerRuntime = class _DockerRuntime {
       { excludes: [] }
     );
   }
+  /**
+   * Is BuildKit usable on the remote host? Probed, never assumed: a plain `docker`
+   * CLI without the buildx plugin HARD-FAILS when BuildKit is requested explicitly
+   * ("BuildKit is enabled but the buildx component is missing or broken"), while an
+   * unadorned `docker build` on the same box falls back to the legacy builder and
+   * works — the same trap {@link buildImage} in system/managed-image.ts documents.
+   * So we ask first, and only then opt in.
+   *
+   * Memoized per adapter instance (one instance ≈ one target daemon), so a compose
+   * batch pays a single `docker buildx version` for N images.
+   */
+  buildKitProbe = null;
+  async remoteBuildKitAvailable() {
+    const executor = this.connectionOptions?.executor;
+    if (!executor) return false;
+    const probe = this.buildKitProbe ??= executor.exec("docker buildx version >/dev/null 2>&1 && echo OPENSHIP_BUILDKIT_OK || true").then((out) => out.split(/\r?\n/).some((line) => line.trim() === "OPENSHIP_BUILDKIT_OK")).catch(() => false);
+    const available = await probe;
+    if (!available) this.buildKitProbe = null;
+    return available;
+  }
   /**
    * 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).
+   * context dir. One image; `dockerfileName` selects which Dockerfile to use (so N
+   * services can build from one transferred tree) and is relative to
+   * `remoteBuildDir` — the build CONTEXT, which for a compose service is its own
+   * `build:` directory inside that tree, not the tree root (#634).
    */
-  async buildImageOnRemote(config, remoteContextDir, dockerfileName, tag, log, signal) {
+  async buildImageOnRemote(config, remoteBuildDir, dockerfileName, tag, log, opts) {
+    const signal = opts?.signal;
     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 resolvedBuildArgs = resolveDockerBuildArgs(config);
+    const buildArgs = Object.entries(resolvedBuildArgs).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}`);
+    const buildKit = await this.remoteBuildKitAvailable();
+    const builderEnv = buildKit ? "DOCKER_BUILDKIT=1 " : "";
+    const builderFlags = buildKit ? " --progress=plain" : " --force-rm";
+    if (buildKit) {
+      log.log("Builder: BuildKit (docker buildx detected on the host)");
+    } else if (opts?.requiresBuildKit) {
+      log.log(
+        "This Dockerfile needs BuildKit, but the build host's docker CLI has no buildx plugin. Install it (`docker-buildx-plugin`, or Docker's official packages) \u2014 the build below will use the legacy builder and is likely to fail.",
+        "warn"
+      );
+    } else {
+      log.log(
+        "Builder: legacy (docker buildx not available on the host) \u2014 BuildKit-only Dockerfile syntax such as `RUN --mount` will not work"
+      );
+    }
+    const buildCmd = `cd ${sq(remoteBuildDir)} && ${builderEnv}docker build${builderFlags} -t ${sq(tag)}${dockerfileFlag} ${labelArgs} ${buildArgs} .`;
+    log.log(
+      `Running Docker build on remote (${Object.keys(resolvedBuildArgs).length} build argument${Object.keys(resolvedBuildArgs).length === 1 ? "" : "s"}; values hidden).`
+    );
     log.log("\u2500\u2500\u2500 docker build output \u2500\u2500\u2500");
-    this.emitDockerStep(log, "install", "running", "Running install inside container (docker build)");
+    this.emitDockerStep(
+      log,
+      "install",
+      "running",
+      "Running install inside container (docker build)"
+    );
     const { code } = await executor.streamExec(
       buildCmd,
       (entry) => {
@@ -6238,7 +6338,11 @@ var DockerRuntime = class _DockerRuntime {
         config.gitSsh
       );
     }
-    const { cloneUrl, gitEnv: GIT_ENV, credFlag: CRED } = assembleGitClone({
+    const {
+      cloneUrl,
+      gitEnv: GIT_ENV,
+      credFlag: CRED
+    } = assembleGitClone({
       repoUrl: config.repoUrl,
       gitToken: config.gitToken,
       gitCredentialHelperPath: config.gitCredentialHelperPath,
@@ -6264,8 +6368,11 @@ var DockerRuntime = class _DockerRuntime {
             `${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");
+          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)}`
           );
@@ -6286,15 +6393,50 @@ var DockerRuntime = class _DockerRuntime {
    * (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`.
+   * (pure fn) and written to the remote tree.
+   *
+   * Returns the build CONTEXT dir on the host plus the Dockerfile path relative to
+   * it — the same pair {@link resolveServiceDockerfile} produces locally, because
+   * these two resolvers are one behaviour with two probes and a narrowed context
+   * learned by only one of them would leave #634 reproducible on this target.
    */
-  async resolveRemoteDockerfile(config, remoteContextDir, generatedName, requireRepositoryDockerfile) {
+  async resolveRemoteDockerfile(config, remoteContextDir, generatedName, requireRepositoryDockerfile, log) {
     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;
+    const contextSubdir = dockerBuildContextDirectory(config);
+    const remoteBuildDir = contextSubdir ? `${remoteContextDir}/${contextSubdir}` : remoteContextDir;
+    if (contextSubdir) {
+      const real = await executor.exec(`cd ${sq(remoteBuildDir)} 2>/dev/null && pwd -P || true`).then((out) => out.trim()).catch(() => "");
+      const root = await executor.exec(`cd ${sq(remoteContextDir)} && pwd -P`).then((out) => out.trim()).catch(() => "");
+      if (!real) {
+        throw new Error(
+          `Build context "${contextSubdir}" is not a directory in the cloned source. Check the service's build path.`
+        );
+      }
+      if (!root || real !== root && !real.startsWith(`${root}/`)) {
+        throw new Error(`Build context "${contextSubdir}" resolves outside the cloned source.`);
+      }
+    }
+    const candidates = contextSubdir ? resolveContextDockerfileCandidates(contextSubdir, config.dockerfilePath) : resolveDockerfileCandidates(config.rootDirectory, config.dockerfilePath);
+    for (const candidate of candidates) {
+      const out = await executor.exec(`test -f ${sq(`${remoteBuildDir}/${candidate}`)} && echo yes || true`).catch(() => "");
+      if (out.trim() === "yes") {
+        const explicit = normalizeDockerRelativePath(config.dockerfilePath);
+        if (contextSubdir && explicit && candidate === "Dockerfile" && explicit !== "Dockerfile" && explicit !== `${contextSubdir}/Dockerfile`) {
+          log?.log(
+            `Configured Dockerfile "${config.dockerfilePath}" was not found in build context "${contextSubdir}" \u2014 using ${contextSubdir}/Dockerfile instead.`,
+            "warn"
+          );
+        }
+        return { remoteBuildDir, dockerfileName: candidate };
+      }
+    }
+    if (contextSubdir) {
+      throw new Error(
+        missingContextDockerfileMessage(contextSubdir, config.dockerfilePath, {
+          generatedRecipeRefused: !requireRepositoryDockerfile
+        })
+      );
     }
     if (requireRepositoryDockerfile) {
       const expected = config.dockerfilePath?.trim() || "Dockerfile";
@@ -6303,7 +6445,7 @@ var DockerRuntime = class _DockerRuntime {
       );
     }
     await executor.writeFile(`${remoteContextDir}/${generatedName}`, generateDockerfile(config));
-    return generatedName;
+    return { remoteBuildDir, dockerfileName: generatedName };
   }
   async buildViaSshTarPipe(config, buildContext, tag, log, signal) {
     const remoteContextDir = `/tmp/openship-build-${config.sessionId}`;
@@ -6311,11 +6453,11 @@ var DockerRuntime = class _DockerRuntime {
       await this.transferBuildContext(buildContext.contextDir, remoteContextDir, log);
       await this.buildImageOnRemote(
         config,
-        remoteContextDir,
+        buildContext.contextSubdir ? `${remoteContextDir}/${buildContext.contextSubdir}` : remoteContextDir,
         buildContext.dockerfileName,
         tag,
         log,
-        signal
+        { signal, requiresBuildKit: buildContext.requiresBuildKit }
       );
     } finally {
       this.connectionOptions?.executor?.exec(`rm -rf ${sq(remoteContextDir)}`).catch(() => {
@@ -6323,6 +6465,41 @@ var DockerRuntime = class _DockerRuntime {
       await buildContext.cleanup();
     }
   }
+  /**
+   * Pick the Engine-API builder for ONE dockerode build, for BOTH dockerode call
+   * sites (single image and compose batch) — they are the same decision and a
+   * builder learned by only one of them is the "two executors" trap all over again.
+   *
+   * The classic builder is kept as the DEFAULT deliberately. It is what every
+   * self-hosted local build has always used; switching wholesale would change layer
+   * caching for everyone and silently drop the build CPU/memory caps, which BuildKit
+   * ignores. So BuildKit is opted into only where the classic builder cannot work at
+   * all — a Dockerfile whose syntax it rejects (#634).
+   *
+   * Through the ENGINE API (`version=2`), not by shelling out to `docker build`,
+   * which is the first alternative that comes to mind and is not available: the API
+   * image ships `openssh-client rsync git` and no docker CLI (apps/api/Dockerfile),
+   * and the transport may be a TCP socket with no shell at the other end at all.
+   * Nothing needs the buildx plugin either — BuildKit lives in the daemon.
+   *
+   * Asymmetric with the remote CLI path on purpose: there, BuildKit is taken whenever
+   * buildx exists, because that command passes no --memory/--cpus (so there is no cap
+   * to lose) and on docker ≥23 the CLI already defaults to it — the prefix mostly
+   * buys the log line and the buildx-missing warning.
+   */
+  selectDockerodeBuilder(config, requiresBuildKit, log) {
+    if (!requiresBuildKit) return { options: {} };
+    log.log(
+      "Dockerfile uses BuildKit-only syntax (RUN --mount, a syntax directive or a heredoc) \u2014 building with BuildKit."
+    );
+    if (Object.keys(dockerBuildResourceLimits(config.resources)).length > 0) {
+      log.log(
+        "Build CPU/memory limits are not enforced under BuildKit \u2014 this build runs uncapped.",
+        "warn"
+      );
+    }
+    return { options: { version: "2" }, trace: new BuildKitTraceDecoder() };
+  }
   /**
    * Dockerode build path. Used for local socket and TCP transports, plus
    * SSH transports that didn't get an executor wired in (shouldn't happen
@@ -6335,32 +6512,34 @@ var DockerRuntime = class _DockerRuntime {
   async buildViaDockerode(config, buildContext, tag, log, cancelSignal) {
     log.log(`Streaming build context to Docker daemon - image tag: ${tag}`);
     const { body, abortSignal, takeError } = packBuildContext(
-      buildContext.contextDir,
+      buildContext.buildContextDir,
       buildContext.contextEntries,
-      cancelSignal
+      cancelSignal,
+      buildContext.ignoreContextPath
     );
+    const builder = this.selectDockerodeBuilder(config, buildContext.requiresBuildKit, log);
     try {
       const stream = await this.docker.buildImage(body, {
         t: tag,
         dockerfile: buildContext.dockerfileName,
         labels: this.labels({ projectId: config.projectId, sessionId: config.sessionId }),
-        buildargs: {
-          ...config.envVars,
-          NODE_ENV: "production"
-        },
+        buildargs: resolveDockerBuildArgs(config),
         // Omitted entirely unless the project set a build cap — a self-hosted
         // build should be free to use the machine (a production build often
         // needs several GB). Opt-in only; see dockerBuildResourceLimits.
         ...dockerBuildResourceLimits(config.resources),
         forcerm: true,
+        ...builder.options,
         abortSignal
       });
       log.log("Connected to Docker daemon. Build output follows:");
-      await this.streamDockerodeBuild(stream, log);
+      await this.streamDockerodeBuild(stream, log, builder.trace);
       log.log("Docker daemon finished streaming build output. Finalizing image...\n");
     } catch (err) {
       const contextErr = takeError();
-      throw contextErr ? new Error(`Failed to read Docker build context: ${safeErrorMessage(contextErr)}`, { cause: contextErr }) : err;
+      throw contextErr ? new Error(`Failed to read Docker build context: ${safeErrorMessage(contextErr)}`, {
+        cause: contextErr
+      }) : err;
     } finally {
       await buildContext.cleanup();
     }
@@ -6370,7 +6549,7 @@ var DockerRuntime = class _DockerRuntime {
    * 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) {
+  async streamDockerodeBuild(stream, log, trace) {
     let fatalBuildError = null;
     await new Promise((resolve, reject) => {
       let settled = false;
@@ -6409,9 +6588,11 @@ var DockerRuntime = class _DockerRuntime {
         }, 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."
-          ));
+          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();
       };
@@ -6427,7 +6608,7 @@ var DockerRuntime = class _DockerRuntime {
         },
         (event) => {
           resetIdleTimer();
-          fatalBuildError ??= this.handleBuildEvent(event, log);
+          fatalBuildError ??= this.handleBuildEvent(event, log, trace);
         }
       );
     });
@@ -6496,20 +6677,16 @@ var DockerRuntime = class _DockerRuntime {
           await this.cloneSourceOnRemote(config, remoteContextDir, log);
           if (abort.signal.aborted) throw new BuildCancelledError();
           this.emitDockerStep(log, "clone", "completed", "Source cloned on the server");
-          const dockerfileName = await this.resolveRemoteDockerfile(
+          const { remoteBuildDir, dockerfileName } = await this.resolveRemoteDockerfile(
             config,
             remoteContextDir,
             "Dockerfile.openship",
-            config.stack === "docker"
-          );
-          await this.buildImageOnRemote(
-            config,
-            remoteContextDir,
-            dockerfileName,
-            tag,
-            log,
-            abort.signal
+            config.stack === "docker",
+            log
           );
+          await this.buildImageOnRemote(config, remoteBuildDir, dockerfileName, tag, log, {
+            signal: abort.signal
+          });
         } finally {
           sshExecutor.exec(`rm -rf ${sq(remoteContextDir)}`).catch(() => {
           });
@@ -6519,7 +6696,12 @@ var DockerRuntime = class _DockerRuntime {
         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 };
+        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, {
@@ -6530,16 +6712,13 @@ var DockerRuntime = class _DockerRuntime {
       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)`
-        );
+        this.emitDockerStep(log, "clone", "completed", `Docker build context ready (${sizeMB} MB)`);
       } catch {
         this.emitDockerStep(log, "clone", "completed", "Docker build context ready");
       }
-      if (buildContext.rootDirectory) {
+      if (buildContext.contextSubdir) {
+        log.log(`Using Docker build context: ${buildContext.contextSubdir}`);
+      } else if (buildContext.rootDirectory) {
         log.log(`Using Docker build root: ${buildContext.rootDirectory}`);
       }
       if (buildContext.usesRepositoryDockerfile) {
@@ -6579,7 +6758,75 @@ var DockerRuntime = class _DockerRuntime {
       if (abort.signal.aborted || err instanceof BuildCancelledError) return cancelled();
       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}` };
+      return {
+        sessionId: config.sessionId,
+        status: "failed",
+        durationMs: Date.now() - startTime,
+        errorMessage: `Docker build failed: ${msg}`
+      };
+    } finally {
+      releaseDockerBuild(config.sessionId, abort);
+    }
+  }
+  /**
+   * Acquire a registry image without ever treating it as a Dockerfile builder.
+   *
+   * The returned digest is preferred over the requested tag so a later deploy
+   * runs exactly the bytes acquired here even if a mutable tag moves between
+   * prepare and deploy. The image is deliberately non-owned: it came from a
+   * registry and may be shared by unrelated containers on the target daemon, so
+   * deployment cleanup must never remove it as if Openship had built it.
+   */
+  async prepareImage(config, logger) {
+    const log = logger ?? new BuildLogger();
+    const startTime = Date.now();
+    const abort = registerDockerBuild(config.sessionId);
+    const cancelled = () => {
+      log.step("build", "failed", "Image pull cancelled");
+      return {
+        sessionId: config.sessionId,
+        status: "cancelled",
+        durationMs: Date.now() - startTime,
+        artifactOwned: false
+      };
+    };
+    try {
+      if (abort.signal.aborted) return cancelled();
+      const requestedRef = config.imageRef.trim();
+      if (!requestedRef) throw new Error("Prebuilt image reference is required");
+      log.step("build", "running", `Pulling prebuilt image ${requestedRef}`);
+      try {
+        await this.ensureDockerFeature(log);
+      } catch (featureErr) {
+        throw new Error(this.formatDockerConnectivityError(featureErr));
+      }
+      await this.pullImage(requestedRef, { force: config.forcePull });
+      if (abort.signal.aborted) return cancelled();
+      const deployRef = await this.resolveImageDigest(requestedRef).catch(() => void 0) ?? requestedRef;
+      log.log(
+        deployRef === requestedRef ? `Image ${requestedRef} is ready.
+` : `Image ${requestedRef} is ready as ${deployRef}.
+`
+      );
+      log.step("build", "completed", `Prebuilt image ${deployRef} is ready`);
+      return {
+        sessionId: config.sessionId,
+        status: "deploying",
+        imageRef: deployRef,
+        durationMs: Date.now() - startTime,
+        artifactOwned: false
+      };
+    } catch (err) {
+      if (abort.signal.aborted) return cancelled();
+      const message = safeErrorMessage(err);
+      log.step("build", "failed", `Image pull failed: ${message}`);
+      return {
+        sessionId: config.sessionId,
+        status: "failed",
+        durationMs: Date.now() - startTime,
+        errorMessage: `Image pull failed: ${message}`,
+        artifactOwned: false
+      };
     } finally {
       releaseDockerBuild(config.sessionId, abort);
     }
@@ -6608,6 +6855,7 @@ var DockerRuntime = class _DockerRuntime {
           await this.extractDocRootViaDaemon(tag, docRoot, hostOutDir);
         }
       }
+      await this.pruneBuildFilesFromDocRoot(config, hostOutDir, sshExecutor ?? null, log);
       log.log(`Static files ready at ${hostOutDir}
 `);
     } finally {
@@ -6692,6 +6940,74 @@ var DockerRuntime = class _DockerRuntime {
    * expensive one: every extractor can succeed having copied nothing, which deploys
    * green and then 404s the entire site.
    */
+  /**
+   * Names that must never end up in a public doc-root, matched at its TOP LEVEL
+   * only.
+   *
+   * `.git` is the repository — serving it publishes full source history. The
+   * Dockerfiles and `.dockerignore` are OUR build inputs, and one of them is
+   * literally written into the tree by `resolveServiceDockerfile`.
+   */
+  static DOC_ROOT_EXCLUDED = [
+    ".dockerignore",
+    ".git",
+    "Dockerfile",
+    "Dockerfile.*"
+  ];
+  /**
+   * Remove build inputs from an extracted static doc-root, then re-assert the
+   * contract that it still holds something servable.
+   *
+   * Only runs when the doc-root IS the build context — `outputDirectory` empty or
+   * "." — which is the zero-build "just files, index.html at the root" project. A
+   * real output directory (`dist`, `build`) is written by the build and contains
+   * none of this, so the prune is a no-op there.
+   *
+   * Two distinct problems, one fix. The build context is pruned by `.dockerignore`
+   * and THEN the generated recipe is written into it, so for these projects the
+   * published site contained `.dockerignore` + `Dockerfile.openship…` — and any
+   * tracked `.git` — at their own public URLs. Worse, those files count as
+   * content: a repo with an allowlist `.dockerignore` (`*` + `!src`) extracted to
+   * a tree holding ONLY the two build files, which passed the non-empty check and
+   * deployed green as a site that 404s every request. Pruning first and
+   * re-checking after is what makes that check mean "there is something to serve".
+   */
+  async pruneBuildFilesFromDocRoot(config, hostOutDir, sshExecutor, log) {
+    if (staticBuilderOutputPath(config) !== builderContextRoot(config)) return;
+    if (sshExecutor) {
+      const globs = _DockerRuntime.DOC_ROOT_EXCLUDED.map((name) => `${sq(hostOutDir)}/${name}`).join(
+        " "
+      );
+      await sshExecutor.exec(`rm -rf ${globs}`).catch(() => {
+      });
+      log.log(`Excluded build files from the published output (${hostOutDir}).
+`);
+      const listing = (await sshExecutor.exec(`ls -A ${sq(hostOutDir)} | head -1`).catch(() => "x")).trim();
+      this.assertDocRootServable(!listing, hostOutDir);
+      return;
+    }
+    const { readdir, rm } = await import("fs/promises");
+    const { join: join3 } = await import("path");
+    const entries = await readdir(hostOutDir).catch(() => null);
+    if (entries === null) return;
+    const doomed = entries.filter((name) => isExcludedDocRootEntry(name));
+    for (const name of doomed) {
+      await rm(join3(hostOutDir, name), { recursive: true, force: true }).catch(() => {
+      });
+    }
+    if (doomed.length > 0) {
+      log.log(`Excluded build files from the published output: ${doomed.join(", ")}
+`);
+    }
+    this.assertDocRootServable(entries.length === doomed.length, hostOutDir);
+  }
+  /** Post-prune half of the doc-root contract: build inputs are not content. */
+  assertDocRootServable(isEmpty, hostOutDir) {
+    if (!isEmpty) return;
+    throw new Error(
+      `the static output at ${hostOutDir} contains only build files (Dockerfile / .dockerignore) and nothing to serve \u2014 check the project's output directory setting and its .dockerignore.`
+    );
+  }
   assertDocRootFilled(isEmpty, docRoot) {
     if (!isEmpty) return;
     throw new Error(
@@ -6783,7 +7099,9 @@ var DockerRuntime = class _DockerRuntime {
           `static extract failed copying ${docRoot} out of the build container (exit ${status.StatusCode})${logs ? `: ${logs.slice(-500)}` : ""}`
         );
       }
-      const entries = (await readdir(hostOutDir).catch(() => [])).filter((e) => e !== probe);
+      const entries = (await readdir(hostOutDir).catch(() => [])).filter(
+        (e) => e !== probe
+      );
       this.assertDocRootFilled(entries.length === 0, docRoot);
       return true;
     } finally {
@@ -6878,7 +7196,25 @@ var DockerRuntime = class _DockerRuntime {
         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 });
+        tree = await prepareSourceTree(source, {
+          onLog: prepareLogger.callback,
+          // Any service building from its OWN `build:` directory makes the source
+          // root's `.dockerignore` the wrong file to prune this SHARED tree with —
+          // it would delete files the other contexts need. Those builds filter their
+          // own context instead; see SourceTree.dockerignorePruned.
+          //
+          // A malformed value throws here; `true` is the safe answer for it, because
+          // it only skips a destructive prune. Letting the throw out would fail the
+          // WHOLE batch, while per-spec resolution below reports it against the one
+          // service that owns it.
+          perServiceBuildContexts: specs.some((spec) => {
+            try {
+              return Boolean(dockerBuildContextDirectory(spec.config));
+            } catch {
+              return true;
+            }
+          })
+        });
       }
       const resolvedList = await Promise.all(
         specs.map(async (spec) => {
@@ -6886,34 +7222,54 @@ var DockerRuntime = class _DockerRuntime {
           const requireRepo = spec.requireRepositoryDockerfile ?? spec.config.stack === "docker";
           try {
             if (cloneOnServer) {
-              const dockerfileName = await this.resolveRemoteDockerfile(
+              const { remoteBuildDir, dockerfileName } = await this.resolveRemoteDockerfile(
                 spec.config,
                 remoteContextDir,
                 generatedName,
-                requireRepo
+                requireRepo,
+                spec.logger
               );
               return {
                 spec,
                 dockerfileName,
+                remoteBuildSubdir: dockerBuildContextDirectory(spec.config),
+                remoteBuildDir,
+                buildContextDir: null,
                 contextEntries: null,
+                ignoreContextPath: void 0,
+                // Only the dockerode branch consults it, and clone-on-server never
+                // reaches that branch (it is SSH by construction).
+                requiresBuildKit: false,
                 error: null
               };
             }
             const resolved = await resolveServiceDockerfile(tree.contextDir, spec.config, {
               requireRepositoryDockerfile: requireRepo,
-              generatedName
+              generatedName,
+              dockerignorePruned: tree.dockerignorePruned,
+              onLog: spec.logger.callback
             });
             return {
               spec,
               dockerfileName: resolved.dockerfileName,
+              remoteBuildSubdir: resolved.contextSubdir,
+              remoteBuildDir: resolved.contextSubdir ? `${remoteContextDir}/${resolved.contextSubdir}` : remoteContextDir,
+              buildContextDir: resolved.buildContextDir,
               contextEntries: resolved.contextEntries,
+              ignoreContextPath: resolved.ignoreContextPath,
+              requiresBuildKit: resolved.requiresBuildKit,
               error: null
             };
           } catch (err) {
             return {
               spec,
               dockerfileName: null,
+              remoteBuildSubdir: "",
+              remoteBuildDir: remoteContextDir,
+              buildContextDir: null,
               contextEntries: null,
+              ignoreContextPath: void 0,
+              requiresBuildKit: false,
               error: safeErrorMessage(err)
             };
           }
@@ -6935,7 +7291,17 @@ var DockerRuntime = class _DockerRuntime {
         }
       }
       const results = [];
-      for (const { spec, dockerfileName, contextEntries, error } of resolvedList) {
+      for (const {
+        spec,
+        dockerfileName,
+        remoteBuildDir,
+        remoteBuildSubdir,
+        buildContextDir,
+        contextEntries,
+        ignoreContextPath,
+        requiresBuildKit,
+        error
+      } of resolvedList) {
         const startedAt = Date.now();
         const tag = this.imageTag(spec.config.slug, spec.config.sessionId);
         const signal = abortControllers.get(spec.config.sessionId)?.signal;
@@ -6958,21 +7324,27 @@ var DockerRuntime = class _DockerRuntime {
         }
         spec.onStart?.();
         try {
+          if (remoteBuildSubdir) {
+            spec.logger.log(`Using Docker build context: ${remoteBuildSubdir}
+`);
+          }
           if (isSsh) {
             await this.buildImageOnRemote(
               spec.config,
-              remoteContextDir,
+              remoteBuildDir,
               dockerfileName,
               tag,
               spec.logger,
-              signal
+              { signal, requiresBuildKit }
             );
           } else {
             const { body, abortSignal, takeError } = packBuildContext(
-              tree.contextDir,
+              buildContextDir ?? tree.contextDir,
               contextEntries ?? [],
-              signal
+              signal,
+              ignoreContextPath
             );
+            const builder = this.selectDockerodeBuilder(spec.config, requiresBuildKit, spec.logger);
             try {
               const stream = await this.docker.buildImage(body, {
                 t: tag,
@@ -6981,15 +7353,19 @@ var DockerRuntime = class _DockerRuntime {
                   projectId: spec.config.projectId,
                   sessionId: spec.config.sessionId
                 }),
-                buildargs: { ...spec.config.envVars, NODE_ENV: "production" },
+                buildargs: resolveDockerBuildArgs(spec.config),
                 ...dockerBuildResourceLimits(spec.config.resources),
                 forcerm: true,
+                ...builder.options,
                 abortSignal
               });
-              await this.streamDockerodeBuild(stream, spec.logger);
+              await this.streamDockerodeBuild(stream, spec.logger, builder.trace);
             } catch (err) {
               const contextErr = takeError();
-              throw contextErr ? new Error(`Failed to read Docker build context: ${safeErrorMessage(contextErr)}`, { cause: contextErr }) : err;
+              throw contextErr ? new Error(
+                `Failed to read Docker build context: ${safeErrorMessage(contextErr)}`,
+                { cause: contextErr }
+              ) : err;
             }
           }
           if (isCancelled(spec.config.sessionId)) {
@@ -7072,10 +7448,10 @@ var DockerRuntime = class _DockerRuntime {
     }
     const containers = await this.docker.listContainers({
       all: true,
-      filters: { label: ["openship.build"] }
+      filters: { label: [OPENSHIP_LABEL.build] }
     });
     for (const c of containers) {
-      const buildId = c.Labels?.["openship.build"];
+      const buildId = c.Labels?.[OPENSHIP_LABEL.build];
       if (!buildId || !cancelCovers(sessionId, buildId)) continue;
       try {
         await this.docker.getContainer(c.Id).remove({ force: true });
@@ -7096,10 +7472,18 @@ var DockerRuntime = class _DockerRuntime {
       throw new Error("Docker deploy requires an imageRef (built image tag)");
     }
     const containerName = `openship-${config.runtimeName || config.projectId}-${config.deploymentId}`;
+    const projectEnv = splitRuntimeEnv(config.envVars);
+    if (projectEnv.dropped.length > 0) {
+      log({
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        level: "warn",
+        message: droppedRuntimeEnvMessage(projectEnv.dropped)
+      });
+    }
     const env = [
       ...config.portless ? [] : [`PORT=${config.port}`],
       `NODE_ENV=${config.environment === "production" ? "production" : "development"}`,
-      ...Object.entries(config.envVars).map(([k, v]) => `${k}=${v}`)
+      ...projectEnv.entries.map(([k, v]) => `${k}=${v}`)
     ];
     const cmd = config.startCommand ? ["sh", "-c", config.startCommand] : void 0;
     const restartPolicy = resolveRestartPolicy(config.restartPolicy);
@@ -7217,6 +7601,11 @@ var DockerRuntime = class _DockerRuntime {
     await container.restart();
   }
   async removeImage(imageRef) {
+    if (isArtifactPathRef(imageRef)) {
+      throw new Error(
+        `"${imageRef}" is a host directory, not an image reference \u2014 remove it with destroy().`
+      );
+    }
     const image = this.docker.getImage(imageRef);
     try {
       await image.remove({ force: true });
@@ -7225,16 +7614,18 @@ var DockerRuntime = class _DockerRuntime {
     }
   }
   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(() => {
-        });
+    if (isArtifactPathRef(containerId)) {
+      if (this.transport.kind === "ssh") {
+        const executor = this.connectionOptions?.executor;
+        if (!executor) {
+          throw new Error(
+            `Cannot remove ${containerId}: the SSH transport has no command executor, and removing it locally would delete the wrong machine's files.`
+          );
+        }
+        await removeManagedArtifact(executor, containerId);
+        return;
       }
+      await removeManagedArtifact(null, containerId);
       return;
     }
     const container = this.docker.getContainer(containerId);
@@ -7274,8 +7665,8 @@ var DockerRuntime = class _DockerRuntime {
     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"],
+      buildId: img.Labels?.[OPENSHIP_LABEL.build],
+      deploymentId: img.Labels?.[OPENSHIP_LABEL.deployment],
       size: img.Size ?? 0
     }));
   }
@@ -7320,7 +7711,7 @@ var DockerRuntime = class _DockerRuntime {
     return containers.map((c) => ({
       containerId: c.Id,
       status: stateMap[(c.State ?? "").toLowerCase().trim()] ?? "stopped",
-      serviceName: c.Labels?.["openship.service"]
+      serviceName: c.Labels?.[OPENSHIP_LABEL.service]
     }));
   }
   // ── Rollback primitives (retention half only) ────────────────────────
@@ -7349,17 +7740,18 @@ var DockerRuntime = class _DockerRuntime {
     }
   }
   async purge(deployment) {
+    const failures = [];
     if (deployment.containerId) {
-      try {
-        await this.destroy(deployment.containerId);
-      } catch {
-      }
+      await this.destroy(deployment.containerId).catch((err) => failures.push(err));
     }
     if (deployment.imageRef && ownsBuiltImage(deployment.imageRef)) {
-      try {
-        await this.removeImage(deployment.imageRef);
-      } catch {
-      }
+      await this.removeImage(deployment.imageRef).catch((err) => failures.push(err));
+    }
+    if (failures.length === 1) throw failures[0];
+    if (failures.length > 1) {
+      throw new Error(
+        failures.map((err) => err instanceof Error ? err.message : String(err)).join("; ")
+      );
     }
   }
   /**
@@ -7367,7 +7759,9 @@ var DockerRuntime = class _DockerRuntime {
    * 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.
+   * outside our control). Returns [] only if the container is already gone;
+   * transport and permission failures propagate so an explicit volume wipe
+   * never destroys the last copy of its mount inventory.
    */
   async inspectNamedVolumes(containerId) {
     try {
@@ -7375,16 +7769,18 @@ var DockerRuntime = class _DockerRuntime {
       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 [];
+    } catch (err) {
+      if (isDockerNotFoundError(err)) return [];
+      throw err;
     }
   }
-  /** Remove a named volume by name. Best-effort - already-gone is fine. */
+  /** Remove a named volume by name. Already-gone is idempotent success. */
   async removeVolume(name) {
     try {
       const volume = this.docker.getVolume(name);
       await volume.remove({ force: true });
-    } catch {
+    } catch (err) {
+      if (!isDockerNotFoundError(err)) throw err;
     }
   }
   // ── Docker discovery (label-agnostic) ────────────────────────────────────
@@ -7598,7 +7994,8 @@ var DockerRuntime = class _DockerRuntime {
     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)}` : ""}`);
+      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);
@@ -7677,7 +8074,7 @@ var DockerRuntime = class _DockerRuntime {
     };
     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);
+    const { ip, hostPort, hostPortByContainerPort } = extractNetworkInfo(data);
     let status;
     if (data.State.Running) {
       status = "running";
@@ -7692,6 +8089,7 @@ var DockerRuntime = class _DockerRuntime {
       status,
       ip,
       hostPort,
+      ...hostPortByContainerPort ? { hostPortByContainerPort } : {},
       uptimeSeconds: uptimeSeconds && uptimeSeconds > 0 ? uptimeSeconds : void 0
     };
   }
@@ -7855,7 +8253,11 @@ var DockerRuntime = class _DockerRuntime {
     });
     stream.on("end", () => {
       if (buffer && !destroyed) {
-        onLog({ timestamp: (/* @__PURE__ */ new Date()).toISOString(), message: buffer, level: parseLogLevel(buffer) });
+        onLog({
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          message: buffer,
+          level: parseLogLevel(buffer)
+        });
         buffer = "";
       }
     });
@@ -8070,15 +8472,9 @@ var DockerRuntime = class _DockerRuntime {
   async inContainerExecutor(containerId) {
     return {
       exec: async (command, opts) => {
-        const { exitCode, stdout, stderr } = await this.execInContainer(
-          containerId,
-          command,
-          opts
-        );
+        const { exitCode, stdout, stderr } = await this.execInContainer(containerId, command, opts);
         if (exitCode !== 0) {
-          throw new Error(
-            stdout.trim() || stderr.trim() || `exec exited with code ${exitCode}`
-          );
+          throw new Error(stdout.trim() || stderr.trim() || `exec exited with code ${exitCode}`);
         }
         return stdout;
       }
@@ -8177,12 +8573,13 @@ var DockerRuntime = class _DockerRuntime {
     const ownNames = /* @__PURE__ */ new Set();
     const foreign = /* @__PURE__ */ new Map();
     for (const c of containers) {
-      const owner = c.Labels?.["openship.project"];
+      const owner = c.Labels?.[OPENSHIP_LABEL.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);
+        else if (!foreign.has(m.Name))
+          foreign.set(m.Name, c.Names?.[0]?.replace(/^\//, "") ?? owner);
       }
     }
     for (const [name, other] of foreign) {
@@ -8231,7 +8628,7 @@ var DockerRuntime = class _DockerRuntime {
       );
       if (onNetwork) continue;
       if (this.cannotJoinNetworks(c)) continue;
-      const service = c.Labels?.["openship.service"];
+      const service = c.Labels?.[OPENSHIP_LABEL.service];
       try {
         await network.connect({
           Container: c.Id,
@@ -8255,7 +8652,7 @@ var DockerRuntime = class _DockerRuntime {
    * 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) {
+  async attachToExternalNetworks(projectId, networkNames, extraContainerIds = []) {
     if (networkNames.length === 0) return;
     let containers;
     try {
@@ -8266,6 +8663,22 @@ var DockerRuntime = class _DockerRuntime {
     } catch {
       return;
     }
+    if (extraContainerIds.length > 0) {
+      const seen = new Set(containers.map((c) => c.Id));
+      for (const id of extraContainerIds) {
+        if (seen.has(id)) continue;
+        try {
+          const info = await this.docker.getContainer(id).inspect();
+          containers.push({
+            Id: info.Id,
+            NetworkSettings: { Networks: info.NetworkSettings?.Networks ?? {} },
+            HostConfig: { NetworkMode: info.HostConfig?.NetworkMode }
+          });
+          seen.add(info.Id);
+        } catch {
+        }
+      }
+    }
     for (const name of networkNames) {
       const network = this.docker.getNetwork(name);
       let netId;
@@ -8286,21 +8699,20 @@ var DockerRuntime = class _DockerRuntime {
         } 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}`
-            );
+            console.warn(`[docker] link-connect failed for ${c.Id.slice(0, 12)} \u2192 ${name}: ${msg}`);
           }
         }
       }
     }
   }
-  /** Remove a project network (best-effort). */
+  /** Remove a project network. Already-gone is idempotent success. */
   async removeNetwork(slug) {
     const networkName = `openship-${slug}`;
     try {
       const network = this.docker.getNetwork(networkName);
       await network.remove();
-    } catch {
+    } catch (err) {
+      if (!isDockerNotFoundError(err)) throw err;
     }
   }
   /**
@@ -8319,9 +8731,17 @@ var DockerRuntime = class _DockerRuntime {
       await existing.remove({ force: true });
     } catch {
     }
+    const serviceEnv = splitRuntimeEnv(config.environment);
+    if (serviceEnv.dropped.length > 0) {
+      log({
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        level: "warn",
+        message: `[${config.serviceName}] ${droppedRuntimeEnvMessage(serviceEnv.dropped)}`
+      });
+    }
     const env = [
       ...config.publicPort && config.environment.PORT === void 0 ? [`PORT=${config.publicPort}`] : [],
-      ...Object.entries(config.environment).map(([k, v]) => `${k}=${v}`)
+      ...serviceEnv.entries.map(([k, v]) => `${k}=${v}`)
     ];
     const cmd = resolveComposeCmd(config);
     const entrypoint = resolveComposeEntrypoint(config.advanced);
@@ -8405,7 +8825,7 @@ var DockerRuntime = class _DockerRuntime {
           deploymentId: config.deploymentId,
           projectId: config.projectId
         }),
-        "openship.service": config.serviceName
+        [OPENSHIP_LABEL.service]: config.serviceName
       },
       ...healthcheck && { Healthcheck: healthcheck },
       ...stopConfig,
@@ -8444,7 +8864,7 @@ var DockerRuntime = class _DockerRuntime {
       throw startErr;
     }
     const data = await container.inspect();
-    const { ip, hostPort } = extractNetworkInfo(data);
+    const { ip, hostPort, hostPortByContainerPort } = extractNetworkInfo(data);
     const imageDigest = await this.resolveImageDigest(config.image).catch(() => void 0);
     log({
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
@@ -8457,6 +8877,7 @@ var DockerRuntime = class _DockerRuntime {
       status: "running",
       ip,
       hostPort,
+      ...hostPortByContainerPort ? { hostPortByContainerPort } : {},
       imageDigest
     };
   }
@@ -8467,6 +8888,16 @@ var DockerRuntime = class _DockerRuntime {
    * RepoDigests) or any inspect error. Works local + SSH (plain inspect, no
    * followProgress). Never throws.
    */
+  /**
+   * PUBLIC because it is the only anchor the update scanner has.
+   *
+   * `resolveDeployedDrift` reads `service_deployment.image_digest` to tell a moved mutable
+   * tag (`:latest`, `:16`) from an unchanged one — a REF comparison can't, since the ref
+   * string is identical either way. A deploy records it here; an ADOPTED stack records
+   * nothing, and an adopted stack is image-mode by definition (registry images, no repo),
+   * so every migrated `postgres:16`/`redis:7` project was told "up to date" forever. The
+   * adopt paths need to read it for a container they did not create.
+   */
   async resolveImageDigest(ref) {
     const info = await this.docker.getImage(ref).inspect();
     const repoDigests = info?.RepoDigests ?? [];
@@ -8483,7 +8914,7 @@ var DockerRuntime = class _DockerRuntime {
 };
 
 export {
-  scopedVolumeName,
+  ensureScopedVolumeName,
   isHostPathSource,
   startExecStream,
   startAttachStream,