@wardby/cli 0.2.1 → 0.4.0

package/dist/providers/jobs/docker-isolation.js

@@ -3,8 +3,23 @@ export const CODING_WORKER_UID = 10001;
 export const CODING_WORKER_GID = 10001;
 // The keeper needs headroom for runc's short-lived exec process plus Node's threads.
 const KEEPER_PIDS_LIMIT = 32;
+/**
+ * The network keeper (a run with services only): owns the run's network namespace so each
+ * service and the worker can share it with `--network container:`, as a pod's containers do.
+ */
+export const NETWORK_KEEPER_PIDS_LIMIT = 32;
+export const NETWORK_KEEPER_MEMORY_MB = 64;
+/** `--cpus 0.1`, as Docker reports it. */
+const NETWORK_KEEPER_NANO_CPUS = 100_000_000;
+/** Idles until stopped, on the worker image's own `node` (every worker image ships it for the storage keeper). */
+export const NETWORK_KEEPER_SCRIPT = "process.once('SIGTERM', () => process.exit(0)); setInterval(() => {}, 2147483647);";
 export const CODING_PROXY_ALIAS = "wardby-proxy";
 export const CODING_PROXY_PORT = 8787;
+/**
+ * The one variable Claude's tool runner receives: its package-registry and service settings as JSON
+ * (claude-tool-setup.ts). Never the run capability.
+ */
+export const CLAUDE_TOOL_SETUP_ENV = "WARDBY_TOOL_SETUP";
 /**
  * The proxy's deny port. Nothing is served here (see coding-proxy/deny-port.ts);
  * it is the enforcement witness — the one destination a run's NetworkPolicy must
@@ -50,6 +65,14 @@ function assertIntegerRange(value, min, max) {
     if (!Number.isSafeInteger(value) || value < min || value > max)
         throw isolationError();
 }
+/**
+ * Which runs the Docker launcher starts services for: Codex and Claude Code. The container that runs
+ * the run's commands (Codex's worker, Claude Code's tool runner) joins the network keeper's
+ * namespace and reaches the services on 127.0.0.1; Claude Code's agent stays on the run network.
+ */
+export function dockerSupportsServicesFor(provider) {
+    return provider === "codex" || provider === "claude-code";
+}
 function validateSpec(spec) {
     if (spec.kind !== "coding-agent" || !/^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,199}$/.test(spec.runId)) {
         throw isolationError();
@@ -61,12 +84,18 @@ function validateSpec(spec) {
     if (spec.provider === "claude-code") {
         if (!spec.toolImage || !isImmutableDockerImage(spec.toolImage))
             throw isolationError();
-        if (spec.limits.cpus < 0.35 || spec.limits.memoryMb < 256 || spec.limits.pids < 32)
+        if (spec.limits.cpus < 0.35 || spec.limits.memoryMb < 256 || spec.limits.pids < CLAUDE_MIN_PIDS)
             throw isolationError();
     }
     else if (spec.toolImage !== undefined) {
         throw isolationError();
     }
+    if (spec.services !== undefined) {
+        // docker-services.ts re-validates every entry against the catalog schema. Both providers' shells
+        // share the network keeper's namespace: Codex's worker, and Claude Code's tool runner.
+        if (spec.services.length === 0)
+            throw isolationError();
+    }
     assertFiniteRange(spec.limits.cpus, 0.1, 32);
     assertIntegerRange(spec.limits.memoryMb, 128, 65_536);
     assertIntegerRange(spec.limits.pids, 16, 4_096);
@@ -85,21 +114,33 @@ function validateDockerObject(value) {
     if (!DOCKER_OBJECT.test(value))
         throw isolationError();
 }
-export function isolationNames(runId) {
+/** The opaque per-run token in every Docker object name; never the run ID itself. */
+export function isolationToken(runId) {
     if (!/^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,199}$/.test(runId))
         throw isolationError();
-    const token = runHash(runId).slice(0, 20);
+    return runHash(runId).slice(0, 20);
+}
+export function isolationNames(runId) {
+    const token = isolationToken(runId);
     return {
         network: `wardby-net-${token}`,
         storageVolume: `wardby-storage-${token}`,
         keeperContainer: `wardby-keeper-${token}`,
         workerContainer: `wardby-worker-${token}`,
         toolContainer: `wardby-tools-${token}`,
+        networkKeeperContainer: `wardby-netns-${token}`,
     };
 }
 function labels(runId) {
     return ["--label", LABEL_MANAGED, "--label", LABEL_COMPONENT, "--label", `io.wardby.run-sha256=${runHash(runId)}`];
 }
+/** The fixed isolation labels every run object carries (docker-services.ts builds with them). */
+export function isolationLabelArgs(runId) {
+    return labels(runId);
+}
+export function hasIsolationLabels(labels, runId) {
+    return hasResourceLabels(labels, runId);
+}
 function storageMountOptions(spec) {
     const inodes = Math.max(4_096, Math.min(262_144, spec.limits.diskMb * 256));
     return `size=${spec.limits.diskMb}m,nr_inodes=${inodes},uid=${CODING_WORKER_UID},gid=${CODING_WORKER_GID},mode=0700,nosuid,nodev`;
@@ -192,6 +233,68 @@ export function buildKeeperCreateArgs(spec) {
         "/opt/wardby/coding-worker/keeper.js",
     ];
 }
+export function buildNetworkKeeperCreateArgs(spec) {
+    validateSpec(spec);
+    if (spec.services === undefined)
+        throw isolationError();
+    const names = isolationNames(spec.runId);
+    return [
+        "container",
+        "create",
+        "--name",
+        names.networkKeeperContainer,
+        "--pull",
+        "never",
+        "--user",
+        `${CODING_WORKER_UID}:${CODING_WORKER_GID}`,
+        "--network",
+        names.network,
+        "--read-only",
+        "--cap-drop",
+        "ALL",
+        "--security-opt",
+        "no-new-privileges=true",
+        "--security-opt",
+        "seccomp=builtin",
+        "--init",
+        "--cgroupns",
+        "private",
+        "--ipc",
+        "none",
+        "--cpus",
+        "0.1",
+        "--memory",
+        `${NETWORK_KEEPER_MEMORY_MB}m`,
+        "--memory-swap",
+        `${NETWORK_KEEPER_MEMORY_MB}m`,
+        "--memory-swappiness",
+        "0",
+        "--pids-limit",
+        String(NETWORK_KEEPER_PIDS_LIMIT),
+        "--restart",
+        "no",
+        "--log-driver",
+        "local",
+        "--log-opt",
+        "max-size=1m",
+        "--log-opt",
+        "max-file=2",
+        ...labels(spec.runId),
+        "--entrypoint",
+        "node",
+        spec.image,
+        "-e",
+        NETWORK_KEEPER_SCRIPT,
+    ];
+}
+/**
+ * The network of the container that runs the run's commands (Codex's worker, Claude Code's tool
+ * runner): the run network, or the network keeper's namespace for a run with services.
+ */
+function workerNetworkMode(spec) {
+    const names = isolationNames(spec.runId);
+    return spec.services === undefined ? names.network : `container:${names.networkKeeperContainer}`;
+}
 export function buildWorkerCreateArgs(spec, proxyPort = CODING_PROXY_PORT) {
     validateSpec(spec);
     assertIntegerRange(proxyPort, 1, 65_535);
@@ -207,7 +310,7 @@ export function buildWorkerCreateArgs(spec, proxyPort = CODING_PROXY_PORT) {
         "--user",
         `${CODING_WORKER_UID}:${CODING_WORKER_GID}`,
         "--network",
-        names.network,
+        workerNetworkMode(spec),
         "--read-only",
         "--cap-drop",
         "ALL",
@@ -262,11 +365,15 @@ export function buildWorkerCreateArgs(spec, proxyPort = CODING_PROXY_PORT) {
         spec.image,
     ];
 }
-function claudeToolLimits(spec) {
+/** The tool runner's shell + npm shim (two Node processes) + npm peak near 30 PIDs; 64 leaves headroom. */
+const CLAUDE_TOOL_PIDS = 64;
+/** A Claude run must leave its agent at least 32 PIDs after the tool runner's share. */
+const CLAUDE_MIN_PIDS = CLAUDE_TOOL_PIDS + 32;
+export function claudeToolLimits(spec) {
     return {
         cpus: 0.25,
         memoryMb: Math.min(512, Math.max(128, Math.floor(spec.limits.memoryMb / 3))),
-        pids: 16,
+        pids: CLAUDE_TOOL_PIDS,
     };
 }
 function claudeAgentLimits(spec) {
@@ -351,7 +458,14 @@ export function buildClaudeAgentCreateArgs(spec, proxyPort = CODING_PROXY_PORT)
         spec.image,
     ];
 }
-/** The tool runner receives only the checkout and socket; it never joins the proxy network. */
+/**
+ * The tool runner receives only the checkout and its own storage subpath; it shares the run's
+ * proxy network with the agent (one room) but holds no capability, so the proxy grants it only
+ * registry access via its own WARDBY_TOOL_SETUP value. For a run with services it joins the network
+ * keeper's namespace instead, which is on that same run network: it reaches the proxy by its alias
+ * and the services on 127.0.0.1, and nothing else. It talks to the agent over the Unix socket in
+ * their shared `tool` storage subpath, which does not depend on either container's network.
+ */
 export function buildClaudeToolRunnerCreateArgs(spec) {
     validateSpec(spec);
     if (spec.provider !== "claude-code" || !spec.toolImage)
@@ -368,8 +482,11 @@ export function buildClaudeToolRunnerCreateArgs(spec) {
         "never",
         "--user",
         `${CODING_WORKER_UID}:${CODING_WORKER_GID}`,
+        // One room (docs/coding-worker-isolation.md): the run's proxy network, like the agent, so npm and
+        // pip reach the registry. It holds no capability, so the proxy refuses it anything else. With
+        // services: the network keeper's namespace on that network, so the services answer on 127.0.0.1.
         "--network",
-        "none",
+        workerNetworkMode(spec),
         "--read-only",
         "--cap-drop",
         "ALL",
@@ -402,6 +519,9 @@ export function buildClaudeToolRunnerCreateArgs(spec) {
         `type=volume,src=${names.storageVolume},dst=${WORKER_PATHS.workspace},volume-subpath=workspace,volume-nocopy`,
         "--mount",
         `type=volume,src=${names.storageVolume},dst=${WORKER_PATHS.tool},volume-subpath=tool,volume-nocopy`,
+        // By name only: the value (claude-tool-setup.ts) is in the docker CLI's environment, never argv.
+        "--env",
+        CLAUDE_TOOL_SETUP_ENV,
         "--restart",
         "no",
         "--stop-signal",
@@ -434,6 +554,7 @@ export function buildDockerIsolationPlan(spec, proxyContainer) {
         keeperCreateArgs: buildKeeperCreateArgs(spec),
         workerCreateArgs: spec.provider === "claude-code" ? buildClaudeAgentCreateArgs(spec) : buildWorkerCreateArgs(spec),
         ...(spec.provider === "claude-code" ? { toolCreateArgs: buildClaudeToolRunnerCreateArgs(spec) } : {}),
+        ...(spec.services !== undefined ? { networkKeeperCreateArgs: buildNetworkKeeperCreateArgs(spec) } : {}),
         proxyNetworkConnectArgs: buildProxyNetworkConnectArgs(spec.runId, proxyContainer),
     };
 }
@@ -520,6 +641,77 @@ export function assertKeeperContainerInspection(container, spec) {
         throw isolationError();
     }
 }
+export function assertNetworkKeeperContainerInspection(container, spec) {
+    validateSpec(spec);
+    if (spec.services === undefined)
+        throw isolationError();
+    const names = isolationNames(spec.runId);
+    const host = container.HostConfig;
+    const security = host?.SecurityOpt ?? [];
+    if (container.Config?.User !== `${CODING_WORKER_UID}:${CODING_WORKER_GID}` ||
+        container.Config?.Image !== spec.image ||
+        !hasResourceLabels(container.Config.Labels, spec.runId) ||
+        host?.NetworkMode !== names.network ||
+        host.ReadonlyRootfs !== true ||
+        host.Privileged !== false ||
+        (host.Binds?.length ?? 0) !== 0 ||
+        (host.CapAdd?.length ?? 0) !== 0 ||
+        !host.CapDrop?.includes("ALL") ||
+        !security.includes("no-new-privileges=true") ||
+        !security.includes("seccomp=builtin") ||
+        host.PidsLimit !== NETWORK_KEEPER_PIDS_LIMIT ||
+        host.Memory !== NETWORK_KEEPER_MEMORY_MB * 1024 * 1024 ||
+        host.MemorySwap !== host.Memory ||
+        // cgroup v2 hosts may report this as null after accepting the explicit
+        // no-swappiness request; MemorySwap still attests that swap is disabled.
+        (host.MemorySwappiness !== 0 && host.MemorySwappiness !== null) ||
+        host.NanoCpus !== NETWORK_KEEPER_NANO_CPUS ||
+        host.CgroupnsMode !== "private" ||
+        host.IpcMode !== "none" ||
+        host.PidMode !== "" ||
+        host.Init !== true ||
+        host.RestartPolicy?.Name !== "no" ||
+        host.LogConfig?.Type !== "local" ||
+        host.LogConfig.Config?.["max-size"] !== "1m" ||
+        host.LogConfig.Config?.["max-file"] !== "2" ||
+        (host.Devices?.length ?? 0) !== 0 ||
+        (host.DeviceRequests?.length ?? 0) !== 0 ||
+        (host.GroupAdd?.length ?? 0) !== 0 ||
+        // The worker and services take their DNS and port view from this container.
+        (host.Dns?.length ?? 0) !== 0 ||
+        (host.DnsOptions?.length ?? 0) !== 0 ||
+        (host.DnsSearch?.length ?? 0) !== 0 ||
+        (host.ExtraHosts?.length ?? 0) !== 0 ||
+        Object.keys(host.PortBindings ?? {}).length !== 0 ||
+        host.PublishAllPorts !== false ||
+        Object.keys(container.NetworkSettings?.Ports ?? {}).length !== 0 ||
+        (host.Mounts?.length ?? 0) !== 0 ||
+        (container.Mounts?.length ?? 0) !== 0 ||
+        Object.keys(container.NetworkSettings?.Networks ?? {}).join(",") !== names.network ||
+        // Exactly the idle script buildNetworkKeeperCreateArgs runs, never the image's own entrypoint.
+        JSON.stringify(container.Config.Entrypoint ?? null) !== JSON.stringify(["node"]) ||
+        JSON.stringify(container.Config.Cmd ?? null) !== JSON.stringify(["-e", NETWORK_KEEPER_SCRIPT])) {
+        throw isolationError();
+    }
+}
+/**
+ * The worker (Codex) or tool runner (Claude Code) of a run without services is on the run network
+ * only. With services it is in the network keeper's namespace: Docker reports `container:<name>`
+ * before start and `container:<id>` after, and lists no networks of its own.
+ */
+function workerNetworkAttested(container, spec, networkKeeperId) {
+    const names = isolationNames(spec.runId);
+    const mode = container.HostConfig?.NetworkMode;
+    const networks = Object.keys(container.NetworkSettings?.Networks ?? {});
+    if (spec.services === undefined) {
+        return mode === names.network && networks.length === 1 && networks[0] === names.network;
+    }
+    const shared = [
+        `container:${names.networkKeeperContainer}`,
+        ...(networkKeeperId ? [`container:${networkKeeperId}`] : []),
+    ];
+    return mode !== undefined && shared.includes(mode) && networks.length === 0;
+}
 export function assertProxyContainerInspection(container, runId) {
     const internalNetwork = isolationNames(runId).network;
     const networks = container.NetworkSettings?.Networks ?? {};
@@ -571,11 +763,10 @@ function assertExactWorkerMounts(container, names) {
         }
     }
 }
-export function assertWorkerContainerInspection(container, spec, expectedCapability) {
+export function assertWorkerContainerInspection(container, spec, expectedCapability, networkKeeperId) {
     validateSpec(spec);
     const names = isolationNames(spec.runId);
     const host = container.HostConfig;
-    const networks = Object.keys(container.NetworkSettings?.Networks ?? {});
     const security = host?.SecurityOpt ?? [];
     const wardbyEnvironment = (container.Config?.Env ?? []).filter((value) => value.startsWith("WARDBY_"));
     if (container.Config?.User !== `${CODING_WORKER_UID}:${CODING_WORKER_GID}` ||
@@ -594,7 +785,7 @@ export function assertWorkerContainerInspection(container, spec, expectedCapabil
         host.PidsLimit !== spec.limits.pids ||
         host.NanoCpus !== Math.round(spec.limits.cpus * 1_000_000_000) ||
         host.ShmSize !== 16 * 1024 * 1024 ||
-        host.NetworkMode !== names.network ||
+        !workerNetworkAttested(container, spec, networkKeeperId) ||
         host.PidMode !== "" ||
         host.RestartPolicy?.Name !== "no" ||
         host.LogConfig?.Type !== "local" ||
@@ -611,9 +802,7 @@ export function assertWorkerContainerInspection(container, spec, expectedCapabil
         (host.GroupAdd?.length ?? 0) !== 0 ||
         Object.keys(host.PortBindings ?? {}).length !== 0 ||
         host.PublishAllPorts !== false ||
-        Object.keys(container.NetworkSettings?.Ports ?? {}).length !== 0 ||
-        networks.length !== 1 ||
-        networks[0] !== names.network) {
+        Object.keys(container.NetworkSettings?.Ports ?? {}).length !== 0) {
         throw isolationError();
     }
     if (wardbyEnvironment.length !== 2 ||
@@ -645,7 +834,7 @@ function assertExactMountSet(container, names, expected) {
             throw isolationError();
     }
 }
-function assertClaudeContainerBaseline(container, image, network, spec, limits) {
+function assertClaudeContainerBaseline(container, image, spec, limits) {
     const host = container.HostConfig;
     const security = host?.SecurityOpt ?? [];
     if (container.Config?.User !== `${CODING_WORKER_UID}:${CODING_WORKER_GID}` ||
@@ -667,7 +856,6 @@ function assertClaudeContainerBaseline(container, image, network, spec, limits)
         host.PidsLimit !== limits.pids ||
         host.NanoCpus !== Math.round(limits.cpus * 1_000_000_000) ||
         host.ShmSize !== 16 * 1024 * 1024 ||
-        host.NetworkMode !== network ||
         host.PidMode !== "" ||
         host.RestartPolicy?.Name !== "no" ||
         host.LogConfig?.Type !== "local" ||
@@ -693,7 +881,7 @@ export function assertClaudeAgentContainerInspection(container, spec, expectedCa
     if (spec.provider !== "claude-code")
         throw isolationError();
     const names = isolationNames(spec.runId);
-    assertClaudeContainerBaseline(container, spec.image, names.network, spec, claudeAgentLimits(spec));
+    assertClaudeContainerBaseline(container, spec.image, spec, claudeAgentLimits(spec));
     const environment = (container.Config?.Env ?? []).filter((value) => value.startsWith("WARDBY_"));
     if (environment.length !== 2 ||
         !environment.includes(`WARDBY_PROXY_URL=http://${CODING_PROXY_ALIAS}:${CODING_PROXY_PORT}`) ||
@@ -704,18 +892,21 @@ export function assertClaudeAgentContainerInspection(container, spec, expectedCa
         { path: WORKER_PATHS.output, writable: true, subpath: "output" },
         { path: WORKER_PATHS.tool, writable: true, subpath: "tool" },
     ]);
-    if (Object.keys(container.NetworkSettings?.Networks ?? {}).join(",") !== names.network)
+    // The agent holds the capability: always on the run network only, never in the keeper's namespace.
+    if (container.HostConfig?.NetworkMode !== names.network ||
+        Object.keys(container.NetworkSettings?.Networks ?? {}).join(",") !== names.network)
         throw isolationError();
 }
-export function assertClaudeToolRunnerContainerInspection(container, spec) {
+export function assertClaudeToolRunnerContainerInspection(container, spec, expectedSetup, networkKeeperId) {
     validateSpec(spec);
     if (spec.provider !== "claude-code" || !spec.toolImage)
         throw isolationError();
     const names = isolationNames(spec.runId);
-    assertClaudeContainerBaseline(container, spec.toolImage, "none", spec, claudeToolLimits(spec));
-    if ((container.Config?.Env ?? []).some((value) => value.startsWith("WARDBY_")))
+    assertClaudeContainerBaseline(container, spec.toolImage, spec, claudeToolLimits(spec));
+    const environment = (container.Config?.Env ?? []).filter((value) => value.startsWith("WARDBY_"));
+    if (environment.length !== 1 || environment[0] !== `${CLAUDE_TOOL_SETUP_ENV}=${expectedSetup}`)
         throw isolationError();
-    if (Object.keys(container.NetworkSettings?.Networks ?? {}).join(",") !== "none")
+    if (!workerNetworkAttested(container, spec, networkKeeperId))
         throw isolationError();
     assertExactMountSet(container, names, [
         { path: WORKER_PATHS.workspace, writable: true, subpath: "workspace" },

package/dist/providers/jobs/docker-services.d.ts

@@ -0,0 +1,35 @@
+import { type ResolvedCodingService } from "../../coding/services/catalog.js";
+import { type DockerContainerInspection } from "./docker-isolation.js";
+import type { JobSpec } from "./types.js";
+/** Every Docker run container is PID-bounded; the catalog has no PID field. */
+export declare const SERVICE_PIDS_LIMIT = 512;
+/** /dev/shm for a service (PostgreSQL's dynamic shared memory): the Kubernetes default size. */
+export declare const SERVICE_SHM_MIB = 64;
+export interface DockerServiceContainer {
+    service: ResolvedCodingService;
+    container: string;
+    createArgs: string[];
+}
+export declare function dockerServiceContainerName(runId: string, serviceName: string): string;
+/** The container names of a spec's services, for stop and cleanup: names only, never launch input. */
+export declare function dockerServiceContainerNames(spec: JobSpec): string[];
+/**
+ * Re-validated here, not trusted from dispatch, as the Kubernetes launcher does. Returns the
+ * schema's parsed output (defaults such as `serviceEnv`/`writablePaths` filled in), never the raw
+ * spec, so a caller never has to guard against a missing default field, and any shape the schema
+ * rejects throws the isolation error rather than surfacing as a TypeError further down.
+ */
+export declare function validateDockerServices(spec: JobSpec): ResolvedCodingService[];
+/** Its data path at its disk size, then SERVICE_SCRATCH_MIB for each writable path: the Kubernetes sizes. */
+export declare function serviceTmpfsOptions(service: ResolvedCodingService): Record<string, string>;
+/** tmpfs pages count against the container's memory cgroup: catalog memory, its disk, and /dev/shm. */
+export declare function serviceMemoryMib(service: ResolvedCodingService): number;
+export declare function buildServiceCreateArgs(spec: JobSpec, service: ResolvedCodingService): string[];
+export declare function buildDockerServicePlan(spec: JobSpec): DockerServiceContainer[];
+/**
+ * Before a service starts: exactly the controls buildServiceCreateArgs asked for. No mounts at all,
+ * so an image VOLUME outside the entry's dataPath/writablePaths (an anonymous, unbounded host
+ * volume) fails here rather than run. Re-validates the spec and requires `service` to be one of its
+ * validated entries (by name and version), rather than trusting the caller's pairing of the two.
+ */
+export declare function assertServiceContainerInspection(container: DockerContainerInspection, spec: JobSpec, service: ResolvedCodingService, networkKeeperId?: string): void;

package/dist/providers/jobs/docker-services.js

@@ -0,0 +1,191 @@
+/**
+ * Coding-run services on the Docker launcher (docs/coding-services.md): one hardened container per
+ * resolved catalog entry, in the run's network keeper's namespace, so it answers on 127.0.0.1
+ * exactly like a Kubernetes sidecar. Pure builders and attestation only: DockerJobLauncher runs
+ * and checks them. The image and environment come from the admin-managed catalog snapshot on the
+ * spec, never from repository content, and are re-validated here rather than trusted from dispatch.
+ */
+import { CODING_SERVICE_NAME } from "../../coding/protocol.js";
+import { StoredCodingServicesSchema } from "../../coding/services/catalog.js";
+import { CODING_WORKER_GID, CODING_WORKER_UID, DOCKER_ISOLATION_ERROR, hasIsolationLabels, isolationLabelArgs, isolationNames, isolationToken, } from "./docker-isolation.js";
+import { SERVICE_SCRATCH_MIB, serviceEphemeralStorageMib } from "./kubernetes-isolation.js";
+/** Every Docker run container is PID-bounded; the catalog has no PID field. */
+export const SERVICE_PIDS_LIMIT = 512;
+/** /dev/shm for a service (PostgreSQL's dynamic shared memory): the Kubernetes default size. */
+export const SERVICE_SHM_MIB = 64;
+function isolationError() {
+    return new Error(DOCKER_ISOLATION_ERROR);
+}
+export function dockerServiceContainerName(runId, serviceName) {
+    if (!CODING_SERVICE_NAME.test(serviceName))
+        throw isolationError();
+    return `wardby-svc-${isolationToken(runId)}-${serviceName}`;
+}
+/** The container names of a spec's services, for stop and cleanup: names only, never launch input. */
+export function dockerServiceContainerNames(spec) {
+    return (spec.services ?? [])
+        .filter((service) => CODING_SERVICE_NAME.test(service.name))
+        .map((service) => dockerServiceContainerName(spec.runId, service.name));
+}
+/**
+ * Re-validated here, not trusted from dispatch, as the Kubernetes launcher does. Returns the
+ * schema's parsed output (defaults such as `serviceEnv`/`writablePaths` filled in), never the raw
+ * spec, so a caller never has to guard against a missing default field, and any shape the schema
+ * rejects throws the isolation error rather than surfacing as a TypeError further down.
+ */
+export function validateDockerServices(spec) {
+    if (spec.services === undefined)
+        return [];
+    const names = spec.services.map((service) => service.name);
+    if (spec.services.length === 0 || new Set(names).size !== names.length) {
+        throw isolationError();
+    }
+    const parsed = StoredCodingServicesSchema.safeParse(spec.services);
+    if (!parsed.success)
+        throw isolationError();
+    return parsed.data;
+}
+/** Its data path at its disk size, then SERVICE_SCRATCH_MIB for each writable path: the Kubernetes sizes. */
+export function serviceTmpfsOptions(service) {
+    const mounts = [
+        { path: service.dataPath, sizeMib: service.resources.diskMib },
+        ...service.writablePaths.map((path) => ({ path, sizeMib: SERVICE_SCRATCH_MIB })),
+    ];
+    return Object.fromEntries(mounts.map(({ path, sizeMib }) => [
+        path,
+        `rw,nosuid,nodev,size=${sizeMib}m,uid=${CODING_WORKER_UID},gid=${CODING_WORKER_GID},mode=0700`,
+    ]));
+}
+/** tmpfs pages count against the container's memory cgroup: catalog memory, its disk, and /dev/shm. */
+export function serviceMemoryMib(service) {
+    return service.resources.memoryMib + serviceEphemeralStorageMib(service) + SERVICE_SHM_MIB;
+}
+export function buildServiceCreateArgs(spec, service) {
+    const names = isolationNames(spec.runId);
+    const memoryMib = serviceMemoryMib(service);
+    const env = Object.entries(service.serviceEnv)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .flatMap(([name, value]) => ["--env", `${name}=${value}`]);
+    return [
+        "container",
+        "create",
+        "--name",
+        dockerServiceContainerName(spec.runId, service.name),
+        "--pull",
+        "never",
+        "--user",
+        `${CODING_WORKER_UID}:${CODING_WORKER_GID}`,
+        "--network",
+        `container:${names.networkKeeperContainer}`,
+        "--read-only",
+        "--cap-drop",
+        "ALL",
+        "--security-opt",
+        "no-new-privileges=true",
+        "--security-opt",
+        "seccomp=builtin",
+        "--cgroupns",
+        "private",
+        "--ipc",
+        "private",
+        "--shm-size",
+        `${SERVICE_SHM_MIB}m`,
+        "--cpus",
+        String(service.resources.cpuMillicores / 1000),
+        "--memory",
+        `${memoryMib}m`,
+        "--memory-swap",
+        `${memoryMib}m`,
+        "--memory-swappiness",
+        "0",
+        "--pids-limit",
+        String(SERVICE_PIDS_LIMIT),
+        ...Object.entries(serviceTmpfsOptions(service)).flatMap(([path, options]) => ["--tmpfs", `${path}:${options}`]),
+        ...env,
+        "--restart",
+        "no",
+        "--log-driver",
+        "local",
+        "--log-opt",
+        "max-size=1m",
+        "--log-opt",
+        "max-file=2",
+        ...isolationLabelArgs(spec.runId),
+        service.image,
+    ];
+}
+export function buildDockerServicePlan(spec) {
+    return validateDockerServices(spec).map((service) => ({
+        service,
+        container: dockerServiceContainerName(spec.runId, service.name),
+        createArgs: buildServiceCreateArgs(spec, service),
+    }));
+}
+/**
+ * Before a service starts: exactly the controls buildServiceCreateArgs asked for. No mounts at all,
+ * so an image VOLUME outside the entry's dataPath/writablePaths (an anonymous, unbounded host
+ * volume) fails here rather than run. Re-validates the spec and requires `service` to be one of its
+ * validated entries (by name and version), rather than trusting the caller's pairing of the two.
+ */
+export function assertServiceContainerInspection(container, spec, service, networkKeeperId) {
+    const validated = validateDockerServices(spec);
+    if (!validated.some((entry) => entry.name === service.name && entry.version === service.version)) {
+        throw isolationError();
+    }
+    const names = isolationNames(spec.runId);
+    const host = container.HostConfig;
+    const security = host?.SecurityOpt ?? [];
+    const env = container.Config?.Env ?? [];
+    const memory = serviceMemoryMib(service) * 1024 * 1024;
+    const networkModes = [
+        `container:${names.networkKeeperContainer}`,
+        ...(networkKeeperId ? [`container:${networkKeeperId}`] : []),
+    ];
+    const expectedTmpfs = serviceTmpfsOptions(service);
+    const actualTmpfs = host?.Tmpfs ?? {};
+    if (container.Config?.User !== `${CODING_WORKER_UID}:${CODING_WORKER_GID}` ||
+        container.Config.Image !== service.image ||
+        !hasIsolationLabels(container.Config.Labels, spec.runId) ||
+        host?.ReadonlyRootfs !== true ||
+        host.Privileged !== false ||
+        (host.Binds?.length ?? 0) !== 0 ||
+        (host.CapAdd?.length ?? 0) !== 0 ||
+        !host.CapDrop?.includes("ALL") ||
+        host.CgroupnsMode !== "private" ||
+        host.IpcMode !== "private" ||
+        host.ShmSize !== SERVICE_SHM_MIB * 1024 * 1024 ||
+        host.Memory !== memory ||
+        host.MemorySwap !== memory ||
+        // cgroup v2 hosts may report this as null after accepting the explicit
+        // no-swappiness request; MemorySwap still attests that swap is disabled.
+        (host.MemorySwappiness !== 0 && host.MemorySwappiness !== null) ||
+        host.PidsLimit !== SERVICE_PIDS_LIMIT ||
+        host.NanoCpus !== service.resources.cpuMillicores * 1_000_000 ||
+        !networkModes.includes(host.NetworkMode ?? "") ||
+        host.PidMode !== "" ||
+        host.RestartPolicy?.Name !== "no" ||
+        host.LogConfig?.Type !== "local" ||
+        host.LogConfig.Config?.["max-size"] !== "1m" ||
+        host.LogConfig.Config?.["max-file"] !== "2" ||
+        !security.includes("no-new-privileges=true") ||
+        !security.includes("seccomp=builtin") ||
+        (host.Devices?.length ?? 0) !== 0 ||
+        (host.DeviceRequests?.length ?? 0) !== 0 ||
+        (host.Dns?.length ?? 0) !== 0 ||
+        (host.DnsOptions?.length ?? 0) !== 0 ||
+        (host.DnsSearch?.length ?? 0) !== 0 ||
+        (host.ExtraHosts?.length ?? 0) !== 0 ||
+        (host.GroupAdd?.length ?? 0) !== 0 ||
+        Object.keys(host.PortBindings ?? {}).length !== 0 ||
+        host.PublishAllPorts !== false ||
+        (host.Mounts?.length ?? 0) !== 0 ||
+        (container.Mounts?.length ?? 0) !== 0 ||
+        Object.keys(container.NetworkSettings?.Networks ?? {}).length !== 0 ||
+        Object.keys(container.NetworkSettings?.Ports ?? {}).length !== 0 ||
+        Object.keys(actualTmpfs).length !== Object.keys(expectedTmpfs).length ||
+        Object.entries(expectedTmpfs).some(([path, options]) => actualTmpfs[path] !== options) ||
+        env.some((value) => value.startsWith("WARDBY_")) ||
+        Object.entries(service.serviceEnv).some(([name, value]) => !env.includes(`${name}=${value}`))) {
+        throw isolationError();
+    }
+}