@redwoodjs/agent-ci 0.1.0

package/dist/docker/container-config.js

@@ -0,0 +1,178 @@
+// ─── Environment variables ────────────────────────────────────────────────────
+/**
+ * Build the Env array for `docker.createContainer()`.
+ */
+export function buildContainerEnv(opts) {
+    const { containerName, registrationToken, repoUrl, dockerApiUrl, githubRepo, headSha, dtuHost, useDirectContainer, } = opts;
+    return [
+        `RUNNER_NAME=${containerName}`,
+        `RUNNER_TOKEN=${registrationToken}`,
+        `RUNNER_REPOSITORY_URL=${repoUrl}`,
+        `GITHUB_API_URL=${dockerApiUrl}`,
+        `GITHUB_SERVER_URL=${repoUrl}`,
+        `GITHUB_REPOSITORY=${githubRepo}`,
+        `AGENT_CI_LOCAL_SYNC=true`,
+        `AGENT_CI_HEAD_SHA=${headSha || "HEAD"}`,
+        `AGENT_CI_DTU_HOST=${dtuHost}`,
+        `ACTIONS_CACHE_URL=${dockerApiUrl}/`,
+        `ACTIONS_RESULTS_URL=${dockerApiUrl}/`,
+        `ACTIONS_RUNTIME_TOKEN=mock_cache_token_123`,
+        `RUNNER_TOOL_CACHE=/opt/hostedtoolcache`,
+        `PATH=/home/runner/externals/node24/bin:/home/runner/externals/node20/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin`,
+        // Force colour output in all child processes (pnpm, Node, etc.)
+        `FORCE_COLOR=1`,
+        // Custom containers may run as root and lack libicu — configure accordingly
+        ...(useDirectContainer
+            ? [`RUNNER_ALLOW_RUNASROOT=1`, `DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1`]
+            : []),
+    ];
+}
+// ─── Bind mounts ──────────────────────────────────────────────────────────────
+/**
+ * Build the Binds array for `docker.createContainer()`.
+ */
+export function buildContainerBinds(opts) {
+    const { hostWorkDir, shimsDir, signalsDir, diagDir, toolCacheDir, pnpmStoreDir, npmCacheDir, bunCacheDir, playwrightCacheDir, warmModulesDir, hostRunnerDir, useDirectContainer, } = opts;
+    const h = toHostPath;
+    return [
+        // When using a custom container, bind-mount the extracted runner
+        ...(useDirectContainer ? [`${h(hostRunnerDir)}:/home/runner`] : []),
+        `${h(hostWorkDir)}:/home/runner/_work`,
+        "/var/run/docker.sock:/var/run/docker.sock",
+        `${h(shimsDir)}:/tmp/agent-ci-shims`,
+        // Pause-on-failure IPC: signal files (paused, retry, abort)
+        ...(signalsDir ? [`${h(signalsDir)}:/tmp/agent-ci-signals`] : []),
+        `${h(diagDir)}:/home/runner/_diag`,
+        `${h(toolCacheDir)}:/opt/hostedtoolcache`,
+        // Package manager caches (persist across runs)
+        `${h(pnpmStoreDir)}:/home/runner/_work/.pnpm-store`,
+        `${h(npmCacheDir)}:/home/runner/.npm`,
+        `${h(bunCacheDir)}:/home/runner/.bun/install/cache`,
+        `${h(playwrightCacheDir)}:/home/runner/.cache/ms-playwright`,
+        // Warm node_modules: mounted outside the workspace so actions/checkout can
+        // delete the symlink without EBUSY. A symlink in the entrypoint points
+        // workspace/node_modules → /tmp/warm-modules.
+        `${h(warmModulesDir)}:/tmp/warm-modules`,
+    ];
+}
+// ─── Container command ────────────────────────────────────────────────────────
+/**
+ * Build the long entrypoint command string for the container.
+ */
+export function buildContainerCmd(opts) {
+    const { svcPortForwardSnippet, dtuPort, dtuHost, useDirectContainer, containerName } = opts;
+    // The runner connects directly to the DTU host (no in-container proxy needed).
+    // The DTU listens on 0.0.0.0 so it's reachable from the container network.
+    const dtuBaseUrl = `http://${dtuHost}:${dtuPort}`;
+    // For direct containers, credentials are pre-baked on the host and bind-mounted
+    // into /home/runner. For the default image, we write them inline in the
+    // entrypoint since /home/runner is baked into the image.
+    const credentialSnippet = useDirectContainer
+        ? ""
+        : `echo '{"agentId":1,"agentName":"${containerName}","poolId":1,"poolName":"Default","serverUrl":"${dtuBaseUrl}","gitHubUrl":"${dtuBaseUrl}/'$GITHUB_REPOSITORY'","workFolder":"_work","ephemeral":true}' > /home/runner/.runner && echo '{"scheme":"OAuth","data":{"clientId":"00000000-0000-0000-0000-000000000000","authorizationUrl":"${dtuBaseUrl}/_apis/oauth2/token","oAuthEndpointUrl":"${dtuBaseUrl}/_apis/oauth2/token","requireFipsCryptography":"False"}}' > /home/runner/.credentials && echo '{"d":"CQpCI+sO2GD1N/JsHHI9zEhMlu5Fcc8mU4O2bO6iscOsagFjvEnTesJgydC/Go1HuOBlx+GT9EG2h7+juS0z2o5n8Mvt5BBxlK+tqoDOs8VfQ9CSUl3hqYRPeNdBfnA1w8ovLW0wqfPO08FWTLI0urYsnwjZ5BQrBM+D7zYeA0aCsKdo75bKmaEKnmqrtIEhb7hE45XQa32Yt0RPCPi8QcQAY2HLHbdWdZYDj6k/UuDvz9H/xlDzwYq6Yikk2RSMArFzaufxCGS9tBZNEACDPYgnZnEMXRcvsnZ9FYbq81KOSifCmq7Yocq+j3rY5zJCD+PIDY9QJwPxB4PGasRKAQ==","dp":"A0sY1oOz1+3uUMiy+I5xGuHGHOrEQPYspd1xGClBYYsa/Za0UDWS7V0Tn1cbRWfWtNe5vTpxcvwQd6UZBwrtHF6R2zyXFhE++PLPhCe0tH4C5FY9i9jUw9Vo8t44i/s5JUHU2B1mEptXFUA0GcVrLKS8toZSgqELSS2Q/YLRxoE=","dq":"GrLC9dPJ5n3VYw51ghCH7tybUN9/Oe4T8d9v4dLQ34RQEWHwRd4g3U3zkvuhpXFPloUTMmkxS7MF5pS1evrtzkay4QUTDv+28s0xRuAsw5qNTzuFygg8t93MvpvTVZ2TNApW6C7NFvkL9NbxAnU8+I61/3ow7i6a7oYJJ0hWAxE=","exponent":"AQAB","inverseQ":"8DVz9FSvEdt5W4B9OjgakZHwGfnhn2VLDUxrsR5ilC5tPC/IgA8C2xEfKQM1t+K/N3pAYHBYQ6EPgtW4kquBS/Sy102xbRI7GSCnUbRtTpWYPOaCn6EaxBNzwWzbp5vCbCGvFqlSu4+OBYRVe+iCj+gAnkmT/TKPhHHbTjJHvw==","modulus":"x0eoW2DD7xsW5YiorMN8pNHVvZk4ED1SHlA/bmVnRz5FjEDnQloMn0nBgIUHxoNArksknrp/FOVJv5sJHJTiRZkOp+ZmH7d3W3gmw63IxK2C5pV+6xfav9jR2+Wt/6FMYMgG2utBdF95oif1f2XREFovHoXkWms2l0CPLLHVPO44Hh9EEmBmjOeMJEZkulHJ44z9y8e+GZ2nYqO0ZiRWQcRObZ0vlRaGg6PPOl4ltay0BfNksMB3NDtlhkdVkAEFQxEaZZDK9NtkvNljXCioP3TyTAbqNUGsYCA5D+IHGZT9An99J9vUqTFP6TKjqUvy9WNiIzaUksCySA0a4SVBkQ==","p":"8fgAdmWy+sTzAN19fYkWMQqeC7t1BCQMo5z5knfVLg8TtwP9ZGqDtoe+r0bGv3UgVsvvDdP/QwRvRVP+5G9l999Y6b4VbSdUbrfPfOgjpPDmRTQzHDve5jh5xBENQoRXYm7PMgHGmjwuFsE/tKtSGTrvt2Z3qcYAo0IOqLLhYmE=","q":"0tXx4+P7gUWePf92UJLkzhNBClvdnmDbIt52Lui7YCARczbN/asCDJxcMy6Bh3qmIx/bNuOUrfzHkYZHfnRw8AGEK80qmiLLPI6jrUBOGRajmzemGQx0W8FWalEQfGdNIv9R2nsegDRoMq255Zo/qX60xQ6abpp0c6UNhVYSjTE="}' > /home/runner/.credentials_rsaparams && `;
+    // Timing helper: date +%s%3N gives epoch milliseconds
+    const T = (label) => `T1=$(date +%s%3N); echo "[agent-ci:boot] ${label}: $((T1-T0))ms"; T0=$T1`;
+    const cmdScript = [
+        `MAYBE_SUDO() { if command -v sudo >/dev/null 2>&1; then sudo -n "$@"; else "$@"; fi; }`,
+        `BOOT_T0=$(date +%s%3N); T0=$BOOT_T0`,
+        // chmod is done host-side in workspacePrepPromise — skip it here
+        `if [ -f /usr/bin/git ]; then MAYBE_SUDO mv /usr/bin/git /usr/bin/git.real 2>/dev/null; MAYBE_SUDO cp -p /tmp/agent-ci-shims/git /usr/bin/git 2>/dev/null; MAYBE_SUDO chmod +x /usr/bin/git 2>/dev/null; fi`,
+        T("git-shim"),
+        `${svcPortForwardSnippet}chmod 666 /var/run/docker.sock 2>/dev/null || true`,
+        T("docker-sock"),
+        `cd /home/runner`,
+        `${credentialSnippet}true`,
+        T("credentials"),
+        `REPO_NAME=$(basename $GITHUB_REPOSITORY)`,
+        `WORKSPACE_PATH=/home/runner/_work/$REPO_NAME/$REPO_NAME`,
+        `mkdir -p $WORKSPACE_PATH`,
+        `ln -sfn /tmp/warm-modules $WORKSPACE_PATH/node_modules`,
+        T("workspace-setup"),
+        `echo "[agent-ci:boot] total: $(($(date +%s%3N)-BOOT_T0))ms"`,
+        `echo "[agent-ci:boot] starting run.sh --once"`,
+        `./run.sh --once`,
+    ].join(" && ");
+    return [...(useDirectContainer ? ["-c"] : ["bash", "-c"]), cmdScript];
+}
+// ─── DTU host resolution ──────────────────────────────────────────────────────
+import fs from "fs";
+import { execSync } from "child_process";
+/**
+ * Resolve the DTU host address that nested Docker containers can reach.
+ * Inside Docker: use the container's own bridge IP.
+ * On host: use `host.docker.internal`.
+ */
+export function resolveDtuHost() {
+    const isInsideDocker = fs.existsSync("/.dockerenv");
+    if (!isInsideDocker) {
+        return "host.docker.internal";
+    }
+    try {
+        const ip = execSync("hostname -I 2>/dev/null | awk '{print $1}'", {
+            encoding: "utf8",
+        }).trim();
+        if (ip) {
+            return ip;
+        }
+    }
+    catch { }
+    return "172.17.0.1"; // fallback to bridge gateway
+}
+/**
+ * Rewrite a DTU URL to be reachable from inside Docker containers.
+ */
+export function resolveDockerApiUrl(dtuUrl, dtuHost) {
+    return dtuUrl.replace("localhost", dtuHost).replace("127.0.0.1", dtuHost);
+}
+let _mountMappings = null;
+/**
+ * When running inside a container with Docker-outside-of-Docker (shared socket),
+ * bind mount paths must use HOST paths, not container paths. This function
+ * inspects our own container's mounts to build a translation table.
+ *
+ * Returns [] when running on bare metal (no translation needed).
+ */
+function getMountMappings() {
+    if (_mountMappings !== null) {
+        return _mountMappings;
+    }
+    if (!fs.existsSync("/.dockerenv")) {
+        _mountMappings = [];
+        return _mountMappings;
+    }
+    try {
+        const containerId = fs.readFileSync("/etc/hostname", "utf8").trim();
+        const json = execSync(`docker inspect ${containerId}`, {
+            encoding: "utf8",
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        const data = JSON.parse(json);
+        const mounts = data[0]?.Mounts || [];
+        _mountMappings = mounts
+            .filter((m) => m.Type === "bind")
+            .map((m) => ({
+            hostPath: m.Source,
+            containerPath: m.Destination,
+        }))
+            // Sort longest containerPath first for greedy matching
+            .sort((a, b) => b.containerPath.length - a.containerPath.length);
+    }
+    catch {
+        _mountMappings = [];
+    }
+    return _mountMappings;
+}
+/**
+ * Translate a local filesystem path to the corresponding Docker host path.
+ * Only applies when running inside a container (Docker-outside-of-Docker).
+ * Returns the path unchanged when running on bare metal.
+ */
+export function toHostPath(localPath) {
+    const mappings = getMountMappings();
+    for (const { containerPath, hostPath } of mappings) {
+        if (localPath === containerPath || localPath.startsWith(containerPath + "/")) {
+            return hostPath + localPath.slice(containerPath.length);
+        }
+    }
+    return localPath;
+}

package/dist/docker/container-config.test.js

@@ -0,0 +1,156 @@
+import { describe, it, expect } from "vitest";
+// ── buildContainerEnv ─────────────────────────────────────────────────────────
+describe("buildContainerEnv", () => {
+    it("builds the standard env array", async () => {
+        const { buildContainerEnv } = await import("./container-config.js");
+        const env = buildContainerEnv({
+            containerName: "runner-1",
+            registrationToken: "tok",
+            repoUrl: "http://dtu:3000/org/repo",
+            dockerApiUrl: "http://dtu:3000",
+            githubRepo: "org/repo",
+            headSha: "abc123",
+            dtuHost: "host.docker.internal",
+            useDirectContainer: false,
+        });
+        expect(env).toContain("RUNNER_NAME=runner-1");
+        expect(env).toContain("GITHUB_REPOSITORY=org/repo");
+        expect(env).toContain("AGENT_CI_HEAD_SHA=abc123");
+        expect(env).toContain("FORCE_COLOR=1");
+        // Should NOT include root-mode vars for standard container
+        expect(env).not.toContain("RUNNER_ALLOW_RUNASROOT=1");
+    });
+    it("adds root-mode env vars for direct container injection", async () => {
+        const { buildContainerEnv } = await import("./container-config.js");
+        const env = buildContainerEnv({
+            containerName: "runner-1",
+            registrationToken: "tok",
+            repoUrl: "http://dtu:3000/org/repo",
+            dockerApiUrl: "http://dtu:3000",
+            githubRepo: "org/repo",
+            dtuHost: "host.docker.internal",
+            useDirectContainer: true,
+        });
+        expect(env).toContain("RUNNER_ALLOW_RUNASROOT=1");
+        expect(env).toContain("DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1");
+    });
+});
+// ── buildContainerBinds ───────────────────────────────────────────────────────
+describe("buildContainerBinds", () => {
+    it("builds standard bind mounts", async () => {
+        const { buildContainerBinds } = await import("./container-config.js");
+        const binds = buildContainerBinds({
+            hostWorkDir: "/tmp/work",
+            shimsDir: "/tmp/shims",
+            diagDir: "/tmp/diag",
+            toolCacheDir: "/tmp/toolcache",
+            pnpmStoreDir: "/tmp/pnpm",
+            npmCacheDir: "/tmp/npm",
+            bunCacheDir: "/tmp/bun",
+            playwrightCacheDir: "/tmp/playwright",
+            warmModulesDir: "/tmp/warm",
+            hostRunnerDir: "/tmp/runner",
+            useDirectContainer: false,
+        });
+        expect(binds).toContain("/tmp/work:/home/runner/_work");
+        expect(binds).toContain("/var/run/docker.sock:/var/run/docker.sock");
+        expect(binds).toContain("/tmp/shims:/tmp/agent-ci-shims");
+        expect(binds).toContain("/tmp/warm:/tmp/warm-modules");
+        // Standard mode should NOT include runner home bind (but _work bind is expected)
+        expect(binds.some((b) => b.endsWith(":/home/runner"))).toBe(false);
+    });
+    it("includes runner bind mount for direct container", async () => {
+        const { buildContainerBinds } = await import("./container-config.js");
+        const binds = buildContainerBinds({
+            hostWorkDir: "/tmp/work",
+            shimsDir: "/tmp/shims",
+            diagDir: "/tmp/diag",
+            toolCacheDir: "/tmp/toolcache",
+            pnpmStoreDir: "/tmp/pnpm",
+            npmCacheDir: "/tmp/npm",
+            bunCacheDir: "/tmp/bun",
+            playwrightCacheDir: "/tmp/playwright",
+            warmModulesDir: "/tmp/warm",
+            hostRunnerDir: "/tmp/runner",
+            useDirectContainer: true,
+        });
+        expect(binds).toContain("/tmp/runner:/home/runner");
+    });
+});
+// ── buildContainerCmd ─────────────────────────────────────────────────────────
+describe("buildContainerCmd", () => {
+    it("starts with bash -c for standard containers", async () => {
+        const { buildContainerCmd } = await import("./container-config.js");
+        const cmd = buildContainerCmd({
+            svcPortForwardSnippet: "",
+            dtuPort: "3000",
+            dtuHost: "localhost",
+            useDirectContainer: false,
+            containerName: "test-runner",
+        });
+        expect(cmd[0]).toBe("bash");
+        expect(cmd[1]).toBe("-c");
+        expect(cmd[2]).toContain("MAYBE_SUDO");
+        expect(cmd[2]).toContain("run.sh --once");
+    });
+    it("starts with -c for direct containers", async () => {
+        const { buildContainerCmd } = await import("./container-config.js");
+        const cmd = buildContainerCmd({
+            svcPortForwardSnippet: "",
+            dtuPort: "3000",
+            dtuHost: "localhost",
+            useDirectContainer: true,
+            containerName: "test-runner",
+        });
+        expect(cmd[0]).toBe("-c");
+        expect(cmd).toHaveLength(2);
+    });
+    it("includes service port forwarding snippet", async () => {
+        const { buildContainerCmd } = await import("./container-config.js");
+        const cmd = buildContainerCmd({
+            svcPortForwardSnippet: "socat TCP-LISTEN:5432,fork TCP:svc-db:5432 & \nsleep 0.3 && ",
+            dtuPort: "3000",
+            dtuHost: "localhost",
+            useDirectContainer: false,
+            containerName: "test-runner",
+        });
+        expect(cmd[2]).toContain("socat TCP-LISTEN:5432");
+    });
+});
+// ── resolveDockerApiUrl ───────────────────────────────────────────────────────
+describe("resolveDockerApiUrl", () => {
+    it("replaces localhost with the DTU host", async () => {
+        const { resolveDockerApiUrl } = await import("./container-config.js");
+        expect(resolveDockerApiUrl("http://localhost:3000", "172.17.0.2")).toBe("http://172.17.0.2:3000");
+    });
+    it("replaces 127.0.0.1 with the DTU host", async () => {
+        const { resolveDockerApiUrl } = await import("./container-config.js");
+        expect(resolveDockerApiUrl("http://127.0.0.1:3000", "host.docker.internal")).toBe("http://host.docker.internal:3000");
+    });
+});
+// ── signalsDir bind-mount ─────────────────────────────────────────────────────
+describe("buildContainerBinds with signalsDir", () => {
+    const baseOpts = {
+        hostWorkDir: "/tmp/work",
+        shimsDir: "/tmp/shims",
+        diagDir: "/tmp/diag",
+        toolCacheDir: "/tmp/toolcache",
+        pnpmStoreDir: "/tmp/pnpm",
+        npmCacheDir: "/tmp/npm",
+        bunCacheDir: "/tmp/bun",
+        playwrightCacheDir: "/tmp/playwright",
+        warmModulesDir: "/tmp/warm",
+        hostRunnerDir: "/tmp/runner",
+        useDirectContainer: false,
+    };
+    it("includes signals bind-mount when signalsDir is provided", async () => {
+        const { buildContainerBinds } = await import("./container-config.js");
+        const binds = buildContainerBinds({ ...baseOpts, signalsDir: "/tmp/signals" });
+        expect(binds).toContain("/tmp/signals:/tmp/agent-ci-signals");
+    });
+    it("omits signals bind-mount when signalsDir is undefined", async () => {
+        const { buildContainerBinds } = await import("./container-config.js");
+        const binds = buildContainerBinds(baseOpts);
+        expect(binds.some((b) => b.includes("agent-ci-signals"))).toBe(false);
+    });
+});

package/dist/docker/service-containers.js

@@ -0,0 +1,205 @@
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+/**
+ * Parse Docker-style health-check flags from the YAML `options:` string.
+ * GitHub Actions uses flags like `--health-cmd="..." --health-interval=5s`.
+ */
+export function parseHealthCheck(options) {
+    const cmdMatch = options.match(/--health-cmd[= ]"([^"]+)"/);
+    if (!cmdMatch) {
+        return undefined;
+    }
+    const intervalMatch = options.match(/--health-interval[= ](\d+)s/);
+    const timeoutMatch = options.match(/--health-timeout[= ](\d+)s/);
+    const retriesMatch = options.match(/--health-retries[= ](\d+)/);
+    return {
+        Test: ["CMD-SHELL", cmdMatch[1]],
+        Interval: parseInt(intervalMatch?.[1] ?? "10", 10) * 1000000000, // nanoseconds
+        Timeout: parseInt(timeoutMatch?.[1] ?? "5", 10) * 1000000000,
+        Retries: parseInt(retriesMatch?.[1] ?? "3", 10),
+    };
+}
+/**
+ * Wait for a container to report "healthy" (Docker HEALTHCHECK).
+ * Falls back to a simple ready check after `timeoutMs` milliseconds.
+ */
+async function waitForHealth(docker, containerId, timeoutMs = 60000, emit) {
+    const deadline = Date.now() + timeoutMs;
+    const start = Date.now();
+    let lastEmit = 0;
+    while (Date.now() < deadline) {
+        try {
+            const info = await docker.getContainer(containerId).inspect();
+            const health = info.State?.Health?.Status;
+            if (health === "healthy") {
+                const elapsed = ((Date.now() - start) / 1000).toFixed(1);
+                emit?.(`  ✓ healthy after ${elapsed}s`);
+                return;
+            }
+            if (health === "unhealthy") {
+                throw new Error(`Service container ${containerId} is unhealthy`);
+            }
+            // If no healthcheck defined, just wait for "running" state
+            if (!health && info.State?.Running) {
+                emit?.(`  ✓ running (no healthcheck)`);
+                return;
+            }
+        }
+        catch (err) {
+            if (err.message?.includes("unhealthy")) {
+                throw err;
+            }
+        }
+        const elapsed = Math.floor((Date.now() - start) / 1000);
+        if (elapsed > lastEmit) {
+            emit?.(`  ⏳ ${elapsed}s / ${timeoutMs / 1000}s — waiting for healthy...`);
+            lastEmit = elapsed;
+        }
+        await new Promise((r) => setTimeout(r, 500));
+    }
+    emit?.(`  ⚠ Service health-check timed out after ${timeoutMs / 1000}s — proceeding anyway`);
+}
+// ─── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Create a Docker network, start all service containers, wait for them to be
+ * healthy, and return context that `local-job.ts` threads into the runner
+ * container config.
+ *
+ * NOTE: Callers must ensure `pruneOrphanedDockerResources()` has been called
+ * *before* launching concurrent runners. Pruning inside this function would
+ * race with sibling runners that have already created their networks.
+ */
+export async function startServiceContainers(docker, services, runnerName, emit) {
+    const networkName = `agent-ci-net-${runnerName}`;
+    const containerIds = [];
+    const portForwards = [];
+    // 1. Create a bridge network
+    await docker.createNetwork({ Name: networkName, Driver: "bridge" });
+    emit?.(`  🔗 Created network ${networkName}`);
+    // 2. Start each service
+    for (const svc of services) {
+        const containerName = `${runnerName}-svc-${svc.name}`;
+        emit?.(`  🐳 Starting service: ${svc.name} (${svc.image})`);
+        // Build env array
+        const envArr = svc.env ? Object.entries(svc.env).map(([k, v]) => `${k}=${v}`) : [];
+        // Build health-check config from options string
+        const healthConfig = svc.options ? parseHealthCheck(svc.options) : undefined;
+        // Parse port mappings (e.g. "3306:3306")
+        const portBindings = {};
+        const exposedPorts = {};
+        for (const portMapping of svc.ports ?? []) {
+            const [hostPort, containerPort] = portMapping.split(":");
+            const key = `${containerPort}/tcp`;
+            exposedPorts[key] = {};
+            portBindings[key] = [{ HostPort: hostPort }];
+        }
+        // Pre-cleanup stale container
+        try {
+            await docker.getContainer(containerName).remove({ force: true });
+        }
+        catch {
+            // doesn't exist — fine
+        }
+        // Pull the image if missing
+        try {
+            await docker.getImage(svc.image).inspect();
+        }
+        catch {
+            emit?.(`  📦 Pulling image ${svc.image}...`);
+            await new Promise((resolve, reject) => {
+                docker.pull(svc.image, (err, stream) => {
+                    if (err) {
+                        return reject(err);
+                    }
+                    docker.modem.followProgress(stream, (err) => {
+                        if (err) {
+                            reject(err);
+                        }
+                        else {
+                            resolve();
+                        }
+                    });
+                });
+            });
+        }
+        const container = await docker.createContainer({
+            Image: svc.image,
+            name: containerName,
+            Env: envArr,
+            ExposedPorts: exposedPorts,
+            Healthcheck: healthConfig,
+            HostConfig: {
+                NetworkMode: networkName,
+                PortBindings: portBindings,
+            },
+            // Add network aliases so the service is reachable by its short name (e.g. `mysql`)
+            // on the Docker bridge, matching how GitHub Actions exposes service containers.
+            NetworkingConfig: {
+                EndpointsConfig: {
+                    [networkName]: {
+                        Aliases: [svc.name],
+                    },
+                },
+            },
+        });
+        await container.start();
+        containerIds.push(container.id);
+        emit?.(`  ✓ Service ${svc.name} started (${container.id.substring(0, 12)}) — alias: ${svc.name}`);
+        // Build port-forward commands so localhost:<port> inside the runner reaches the service.
+        // Uses the service container's Docker-network hostname (its container name).
+        for (const portMapping of svc.ports ?? []) {
+            const [hostPort, containerPort] = portMapping.split(":");
+            const fwdPort = containerPort || hostPort;
+            // Python TCP forwarder (same pattern used for DTU forwarding in local-job.ts)
+            portForwards.push(`sudo -n python3 -c "
+import socket,threading
+def fwd(s,d):
+ try:
+  while True:
+   x=s.recv(65536)
+   if not x: break
+   d.sendall(x)
+ except: pass
+ finally: s.close();d.close()
+def handle(c):
+ s=socket.socket();s.connect(('${containerName}',${fwdPort}));threading.Thread(target=fwd,args=(c,s),daemon=True).start();fwd(s,c)
+srv=socket.socket();srv.setsockopt(socket.SOL_SOCKET,socket.SO_REUSEADDR,1);srv.bind(('127.0.0.1',${fwdPort}));srv.listen(32)
+while True:
+ c,_=srv.accept();threading.Thread(target=handle,args=(c,),daemon=True).start()
+" &`);
+        }
+    }
+    // 3. Wait for all services to become healthy
+    for (let i = 0; i < containerIds.length; i++) {
+        const svc = services[i];
+        if (svc.options?.includes("--health-cmd")) {
+            emit?.(`  ⏳ Waiting for ${svc.name} to become healthy (timeout: 60s)...`);
+            const t0 = Date.now();
+            await waitForHealth(docker, containerIds[i], 60000, emit);
+            const took = ((Date.now() - t0) / 1000).toFixed(1);
+            emit?.(`  ✓ ${svc.name} healthy in ${took}s`);
+        }
+    }
+    return { networkName, containerIds, portForwards };
+}
+/**
+ * Stop and remove all service containers, then remove the shared network.
+ */
+export async function cleanupServiceContainers(docker, ctx, emit) {
+    for (const id of ctx.containerIds) {
+        try {
+            const c = docker.getContainer(id);
+            await c.stop({ t: 2 }).catch(() => { });
+            await c.remove({ force: true });
+        }
+        catch {
+            // already gone
+        }
+    }
+    try {
+        await docker.getNetwork(ctx.networkName).remove();
+    }
+    catch {
+        // already gone
+    }
+    emit?.(`  🧹 Cleaned up service containers and network ${ctx.networkName}`);
+}