@redwoodjs/agent-ci 0.7.1 → 0.8.1

package/dist/commit-status.js

@@ -2,9 +2,13 @@ import { execSync } from "child_process";
 import { config } from "./config.js";
 /**
  * Post a GitHub commit status via the `gh` CLI.
- * Silently skips if `gh` is not available on PATH.
+ * Only called when --commit-status is passed. Requires a GitHub token.
  */
-export function postCommitStatus(results, sha) {
+export function postCommitStatus(results, sha, githubToken) {
+    if (!githubToken) {
+        console.warn("[Agent CI] --commit-status requires a GitHub token. Use --github-token or set AGENT_CI_GITHUB_TOKEN.");
+        return;
+    }
     // Check if gh CLI is available
     try {
         execSync("which gh", { stdio: "ignore" });
@@ -25,7 +29,7 @@ export function postCommitStatus(results, sha) {
         return;
     }
     const repo = config.GITHUB_REPO;
-    if (repo === "unknown/unknown") {
+    if (!repo) {
         return;
     }
     const passed = results.filter((r) => r.succeeded).length;

package/dist/config.js

@@ -3,28 +3,55 @@ import fs from "fs";
 import path from "path";
 import { PROJECT_ROOT } from "./output/working-directory.js";
 /**
- * Derive `owner/repo` from the git remote URL.
- * Falls back to "unknown/unknown" if detection fails.
+ * Get the URL of the first git remote, preferring 'origin'.
+ * Uses `git remote get-url` which is scoped to the repo (unlike `git config`
+ * which can leak values from global/system config on CI runners).
  */
-function deriveGithubRepo() {
+export function getFirstRemoteUrl(cwd) {
+    const exec = (cmd) => execSync(cmd, { cwd, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim();
     try {
-        const remoteUrl = execSync("git remote get-url origin", {
-            cwd: PROJECT_ROOT,
-            encoding: "utf-8",
-        }).trim();
-        // Handles both SSH (git@github.com:owner/repo.git) and HTTPS URLs
-        const match = remoteUrl.match(/[/:]([^/]+\/[^/]+?)(?:\.git)?$/);
-        if (match) {
-            return match[1];
-        }
+        return exec("git remote get-url origin") || null;
     }
     catch {
-        // git not available or no remote configured
+        // origin doesn't exist — fall back to the first listed remote
+        try {
+            const firstName = exec("git remote").split("\n")[0];
+            if (firstName) {
+                return exec(`git remote get-url ${firstName}`) || null;
+            }
+        }
+        catch { }
+    }
+    return null;
+}
+/**
+ * Extract `owner/repo` from a git remote URL.
+ * Handles HTTPS, SSH (git@), and ssh:// URLs, with or without `.git` suffix.
+ */
+export function parseRepoSlug(remoteUrl) {
+    const match = remoteUrl.match(/[/:]([^/]+\/[^/]+?)(?:\.git)?\/?$/);
+    return match ? match[1] : null;
+}
+/**
+ * Detect `owner/repo` from the git remote in the given directory.
+ * Throws if detection fails and no fallback is provided.
+ */
+export function resolveRepoSlug(cwd, fallback) {
+    const remoteUrl = getFirstRemoteUrl(cwd);
+    if (remoteUrl) {
+        const slug = parseRepoSlug(remoteUrl);
+        if (slug) {
+            return slug;
+        }
+    }
+    if (fallback !== undefined) {
+        return fallback;
     }
-    return "unknown/unknown";
+    throw new Error(`Could not detect GitHub repository from git remotes in ${cwd}. ` +
+        `Set the GITHUB_REPO environment variable (e.g. GITHUB_REPO=owner/repo).`);
 }
 export const config = {
-    GITHUB_REPO: process.env.GITHUB_REPO || deriveGithubRepo(),
+    GITHUB_REPO: process.env.GITHUB_REPO,
     GITHUB_API_URL: process.env.GITHUB_API_URL || "http://localhost:8910",
 };
 /**

package/dist/config.test.js

@@ -0,0 +1,157 @@
+import { execSync } from "child_process";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { config, getFirstRemoteUrl, parseRepoSlug, resolveRepoSlug } from "./config.js";
+describe("parseRepoSlug", () => {
+    it.each([
+        ["https://github.com/redwoodjs/agent-ci.git", "redwoodjs/agent-ci"],
+        ["https://github.com/redwoodjs/agent-ci", "redwoodjs/agent-ci"],
+        ["https://github.com/redwoodjs/agent-ci/", "redwoodjs/agent-ci"],
+        ["git@github.com:redwoodjs/agent-ci.git", "redwoodjs/agent-ci"],
+        ["git@github.com:redwoodjs/agent-ci", "redwoodjs/agent-ci"],
+        ["ssh://git@github.com/redwoodjs/agent-ci.git", "redwoodjs/agent-ci"],
+        ["ssh://git@github.com/redwoodjs/agent-ci", "redwoodjs/agent-ci"],
+        ["ssh://git@github.com:22/redwoodjs/agent-ci.git", "redwoodjs/agent-ci"],
+        ["https://github.example.com/redwoodjs/agent-ci.git", "redwoodjs/agent-ci"],
+        ["git@github.example.com:redwoodjs/agent-ci.git", "redwoodjs/agent-ci"],
+    ])("parses %s → %s", (url, expected) => {
+        expect(parseRepoSlug(url)).toBe(expected);
+    });
+    it("returns null for unparseable URLs", () => {
+        expect(parseRepoSlug("not-a-url")).toBeNull();
+        expect(parseRepoSlug("")).toBeNull();
+    });
+});
+describe("getFirstRemoteUrl", () => {
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "config-test-"));
+        execSync("git init", { cwd: tmpDir, stdio: "pipe" });
+    });
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it("returns origin URL when origin exists", () => {
+        execSync("git remote add origin https://github.com/test/repo.git", {
+            cwd: tmpDir,
+            stdio: "pipe",
+        });
+        expect(getFirstRemoteUrl(tmpDir)).toBe("https://github.com/test/repo.git");
+    });
+    it("falls back to first remote when origin does not exist", () => {
+        execSync("git remote add upstream https://github.com/test/upstream.git", {
+            cwd: tmpDir,
+            stdio: "pipe",
+        });
+        expect(getFirstRemoteUrl(tmpDir)).toBe("https://github.com/test/upstream.git");
+    });
+    it("prefers origin over other remotes", () => {
+        execSync("git remote add upstream https://github.com/test/upstream.git", {
+            cwd: tmpDir,
+            stdio: "pipe",
+        });
+        execSync("git remote add origin https://github.com/test/origin.git", {
+            cwd: tmpDir,
+            stdio: "pipe",
+        });
+        expect(getFirstRemoteUrl(tmpDir)).toBe("https://github.com/test/origin.git");
+    });
+    it("returns null when no remotes exist", () => {
+        expect(getFirstRemoteUrl(tmpDir)).toBeNull();
+    });
+    it("returns null for non-git directory", () => {
+        const nonGitDir = fs.mkdtempSync(path.join(os.tmpdir(), "no-git-"));
+        try {
+            expect(getFirstRemoteUrl(nonGitDir)).toBeNull();
+        }
+        finally {
+            fs.rmSync(nonGitDir, { recursive: true, force: true });
+        }
+    });
+});
+describe("resolveRepoSlug", () => {
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "config-test-"));
+        execSync("git init", { cwd: tmpDir, stdio: "pipe" });
+    });
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it("detects owner/repo from remote URL", () => {
+        execSync("git remote add origin https://github.com/acme/widgets.git", {
+            cwd: tmpDir,
+            stdio: "pipe",
+        });
+        expect(resolveRepoSlug(tmpDir)).toBe("acme/widgets");
+    });
+    it("detects owner/repo from SSH remote", () => {
+        execSync("git remote add origin git@github.com:acme/widgets.git", {
+            cwd: tmpDir,
+            stdio: "pipe",
+        });
+        expect(resolveRepoSlug(tmpDir)).toBe("acme/widgets");
+    });
+    it("throws when no remotes exist and no fallback given", () => {
+        expect(() => resolveRepoSlug(tmpDir)).toThrow(/Could not detect GitHub repository/);
+    });
+    it("returns fallback when no remotes exist", () => {
+        expect(resolveRepoSlug(tmpDir, "org/fallback")).toBe("org/fallback");
+    });
+    it("throws for non-git directory without fallback", () => {
+        const nonGitDir = fs.mkdtempSync(path.join(os.tmpdir(), "no-git-"));
+        try {
+            expect(() => resolveRepoSlug(nonGitDir)).toThrow(/Could not detect GitHub repository/);
+        }
+        finally {
+            fs.rmSync(nonGitDir, { recursive: true, force: true });
+        }
+    });
+    it("uses non-origin remote when origin is absent", () => {
+        execSync("git remote add upstream https://github.com/acme/upstream.git", {
+            cwd: tmpDir,
+            stdio: "pipe",
+        });
+        expect(resolveRepoSlug(tmpDir)).toBe("acme/upstream");
+    });
+});
+describe("GITHUB_REPO env var override priority", () => {
+    let tmpDir;
+    let savedRepo;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "config-test-"));
+        execSync("git init", { cwd: tmpDir, stdio: "pipe" });
+        savedRepo = config.GITHUB_REPO;
+    });
+    afterEach(() => {
+        config.GITHUB_REPO = savedRepo;
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it("env var overrides auto-detection", () => {
+        execSync("git remote add origin https://github.com/detected/repo.git", {
+            cwd: tmpDir,
+            stdio: "pipe",
+        });
+        config.GITHUB_REPO = "override/from-env";
+        // Replicate cli.ts priority: env var ?? auto-detect
+        const result = config.GITHUB_REPO ?? resolveRepoSlug(tmpDir);
+        expect(result).toBe("override/from-env");
+    });
+    it("auto-detects when env var is not set", () => {
+        execSync("git remote add origin https://github.com/detected/repo.git", {
+            cwd: tmpDir,
+            stdio: "pipe",
+        });
+        config.GITHUB_REPO = undefined;
+        const result = config.GITHUB_REPO ?? resolveRepoSlug(tmpDir);
+        expect(result).toBe("detected/repo");
+    });
+    it("throws when neither env var nor remote is available", () => {
+        config.GITHUB_REPO = undefined;
+        expect(() => {
+            return config.GITHUB_REPO ?? resolveRepoSlug(tmpDir);
+        }).toThrow(/Could not detect GitHub repository/);
+    });
+});

package/dist/docker/container-config.js

@@ -33,13 +33,13 @@ export function buildContainerEnv(opts) {
  * 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 { hostWorkDir, shimsDir, signalsDir, diagDir, toolCacheDir, pnpmStoreDir, npmCacheDir, bunCacheDir, playwrightCacheDir, warmModulesDir, hostRunnerDir, useDirectContainer, dockerSocketPath = "/var/run/docker.sock", } = 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",
+        `${dockerSocketPath}:/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`] : []),
@@ -52,8 +52,10 @@ export function buildContainerBinds(opts) {
         `${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`,
+        // workspace/node_modules → /tmp/node_modules.
+        // Mounted at /tmp/node_modules (not /tmp/warm-modules) so that TypeScript's
+        // upward @types walk from .pnpm realpath finds /tmp/node_modules/@types.
+        `${h(warmModulesDir)}:/tmp/node_modules`,
     ];
 }
 // ─── Container command ────────────────────────────────────────────────────────
@@ -87,7 +89,7 @@ export function buildContainerCmd(opts) {
         `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`,
+        `ln -sfn /tmp/node_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"`,

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

@@ -58,9 +58,9 @@ describe("buildContainerBinds", () => {
             useDirectContainer: false,
         });
         expect(binds).toContain("/tmp/work:/home/runner/_work");
-        expect(binds).toContain("/var/run/docker.sock:/var/run/docker.sock");
+        expect(binds).toContain("/var/run/docker.sock:/var/run/docker.sock"); // default when dockerSocketPath is not set
         expect(binds).toContain("/tmp/shims:/tmp/agent-ci-shims");
-        expect(binds).toContain("/tmp/warm:/tmp/warm-modules");
+        expect(binds).toContain("/tmp/warm:/tmp/node_modules");
         expect(binds).toContain("/tmp/pnpm:/home/runner/_work/.pnpm-store");
         expect(binds).toContain("/tmp/npm:/home/runner/.npm");
         expect(binds).toContain("/tmp/bun:/home/runner/.bun/install/cache");
@@ -101,6 +101,22 @@ describe("buildContainerBinds", () => {
         expect(binds.some((b) => b.includes(".pnpm-store"))).toBe(false);
         expect(binds.some((b) => b.includes(".bun"))).toBe(false);
     });
+    it("uses resolved dockerSocketPath for bind mount when provided", async () => {
+        const { buildContainerBinds } = await import("./container-config.js");
+        const binds = buildContainerBinds({
+            hostWorkDir: "/tmp/work",
+            shimsDir: "/tmp/shims",
+            diagDir: "/tmp/diag",
+            toolCacheDir: "/tmp/toolcache",
+            playwrightCacheDir: "/tmp/playwright",
+            warmModulesDir: "/tmp/warm",
+            hostRunnerDir: "/tmp/runner",
+            useDirectContainer: false,
+            dockerSocketPath: "/Users/test/.orbstack/run/docker.sock",
+        });
+        expect(binds).toContain("/Users/test/.orbstack/run/docker.sock:/var/run/docker.sock");
+        expect(binds).not.toContain("/var/run/docker.sock:/var/run/docker.sock");
+    });
     it("includes runner bind mount for direct container", async () => {
         const { buildContainerBinds } = await import("./container-config.js");
         const binds = buildContainerBinds({
@@ -295,6 +311,33 @@ describe("resolveDockerExtraHosts", () => {
         expect(resolveDockerExtraHosts("10.10.10.10")).toBeUndefined();
     });
 });
+// ── dockerSocketPath bind-mount ───────────────────────────────────────────────
+describe("buildContainerBinds with dockerSocketPath", () => {
+    const baseOpts = {
+        hostWorkDir: "/tmp/work",
+        shimsDir: "/tmp/shims",
+        diagDir: "/tmp/diag",
+        toolCacheDir: "/tmp/toolcache",
+        playwrightCacheDir: "/tmp/playwright",
+        warmModulesDir: "/tmp/warm",
+        hostRunnerDir: "/tmp/runner",
+        useDirectContainer: false,
+    };
+    it("uses default /var/run/docker.sock when no dockerSocketPath is provided", async () => {
+        const { buildContainerBinds } = await import("./container-config.js");
+        const binds = buildContainerBinds(baseOpts);
+        expect(binds).toContain("/var/run/docker.sock:/var/run/docker.sock");
+    });
+    it("uses custom host socket path from dockerSocketPath", async () => {
+        const { buildContainerBinds } = await import("./container-config.js");
+        const binds = buildContainerBinds({
+            ...baseOpts,
+            dockerSocketPath: "/Users/foo/.docker/run/docker.sock",
+        });
+        expect(binds).toContain("/Users/foo/.docker/run/docker.sock:/var/run/docker.sock");
+        expect(binds).not.toContain("/var/run/docker.sock:/var/run/docker.sock");
+    });
+});
 // ── signalsDir bind-mount ─────────────────────────────────────────────────────
 describe("buildContainerBinds with signalsDir", () => {
     const baseOpts = {

package/dist/docker/docker-socket.js

@@ -0,0 +1,119 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { execSync } from "child_process";
+import { debugRunner } from "../output/debug.js";
+const DEFAULT_SOCKET = "/var/run/docker.sock";
+/**
+ * Well-known Docker socket paths on macOS, checked in order.
+ * Linux distros almost always have /var/run/docker.sock directly.
+ */
+const MACOS_PROVIDER_SOCKETS = [
+    path.join(os.homedir(), ".orbstack/run/docker.sock"),
+    path.join(os.homedir(), ".docker/run/docker.sock"),
+    path.join(os.homedir(), ".colima/default/docker.sock"),
+    path.join(os.homedir(), ".lima/docker/sock/docker.sock"),
+];
+/**
+ * Try to extract the socket path from the active Docker context.
+ * Returns undefined if the command fails or the context uses a non-unix endpoint.
+ */
+function socketFromDockerContext() {
+    try {
+        const json = execSync("docker context inspect", {
+            encoding: "utf8",
+            stdio: ["pipe", "pipe", "pipe"],
+            timeout: 5000,
+        });
+        const data = JSON.parse(json);
+        const host = data?.[0]?.Endpoints?.docker?.Host;
+        if (host && host.startsWith("unix://")) {
+            const socketPath = host.replace("unix://", "");
+            if (fs.existsSync(socketPath)) {
+                return socketPath;
+            }
+            debugRunner(`Docker context points to ${socketPath} but it does not exist`);
+        }
+    }
+    catch {
+        debugRunner("Could not inspect Docker context");
+    }
+    return undefined;
+}
+/**
+ * Resolve the Docker daemon socket.
+ *
+ * Resolution order:
+ *  1. `DOCKER_HOST` env var (returned as-is for non-unix schemes)
+ *  2. Default socket `/var/run/docker.sock` (resolves symlinks)
+ *  3. Active Docker context (`docker context inspect`)
+ *  4. Well-known macOS provider sockets
+ *
+ * Throws with actionable guidance when no socket can be found.
+ */
+export function resolveDockerSocket() {
+    // 1. Explicit DOCKER_HOST
+    const envHost = process.env.DOCKER_HOST?.trim();
+    if (envHost) {
+        if (envHost.startsWith("unix://")) {
+            const socketPath = envHost.replace("unix://", "");
+            const resolved = resolveIfExists(socketPath);
+            if (resolved) {
+                return { socketPath: resolved, uri: `unix://${resolved}` };
+            }
+            // The env var points to a non-existent socket — fall through to auto-detect
+            debugRunner(`DOCKER_HOST=${envHost} does not exist, trying auto-detection`);
+        }
+        else {
+            // Non-unix scheme (ssh://, tcp://, etc.) — cannot resolve a local path
+            // Return a sentinel; callers handle non-unix hosts separately.
+            return { socketPath: "", uri: envHost };
+        }
+    }
+    // 2. Default socket path (often a symlink on macOS)
+    const defaultResolved = resolveIfExists(DEFAULT_SOCKET);
+    if (defaultResolved) {
+        return { socketPath: defaultResolved, uri: `unix://${defaultResolved}` };
+    }
+    // 3. Docker context
+    const contextSocket = socketFromDockerContext();
+    if (contextSocket) {
+        return { socketPath: contextSocket, uri: `unix://${contextSocket}` };
+    }
+    // 4. Well-known macOS provider paths
+    if (process.platform === "darwin") {
+        for (const candidate of MACOS_PROVIDER_SOCKETS) {
+            if (fs.existsSync(candidate)) {
+                return { socketPath: candidate, uri: `unix://${candidate}` };
+            }
+        }
+    }
+    // Nothing found — give the user actionable guidance
+    const searched = [
+        DEFAULT_SOCKET,
+        ...(process.platform === "darwin" ? MACOS_PROVIDER_SOCKETS : []),
+    ];
+    const lines = [
+        "Could not find a Docker socket. Searched:",
+        ...searched.map((p) => `  - ${p}`),
+        "",
+        "To fix this, either:",
+        "  • Set the DOCKER_HOST environment variable (e.g. DOCKER_HOST=unix:///path/to/docker.sock)",
+        `  • Create a symlink:  ln -s /path/to/docker.sock ${DEFAULT_SOCKET}`,
+        "  • Start your Docker provider (Docker Desktop, OrbStack, Colima, etc.)",
+    ];
+    throw new Error(lines.join("\n"));
+}
+/**
+ * If `socketPath` exists (following symlinks), return the real path.
+ * Returns undefined otherwise.
+ */
+function resolveIfExists(socketPath) {
+    try {
+        // fs.realpathSync follows symlinks and throws if the target doesn't exist
+        return fs.realpathSync(socketPath);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/docker/docker-socket.test.js

@@ -0,0 +1,117 @@
+import { describe, it, expect, afterEach, vi } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import { execSync } from "node:child_process";
+vi.mock("node:child_process", () => ({
+    execSync: vi.fn(),
+}));
+const mockedExecSync = vi.mocked(execSync);
+afterEach(() => {
+    vi.restoreAllMocks();
+    delete process.env.DOCKER_HOST;
+});
+// Helper to dynamically import (fresh module each test via vi.resetModules)
+async function importFresh() {
+    vi.resetModules();
+    return import("./docker-socket.js");
+}
+describe("resolveDockerSocket", () => {
+    // ── DOCKER_HOST set ──────────────────────────────────────────────────────
+    it("uses DOCKER_HOST when set to a unix socket that exists", async () => {
+        process.env.DOCKER_HOST = "unix:///tmp/test-docker.sock";
+        vi.spyOn(fs, "realpathSync").mockReturnValue("/tmp/test-docker.sock");
+        const { resolveDockerSocket } = await importFresh();
+        const result = resolveDockerSocket();
+        expect(result.socketPath).toBe("/tmp/test-docker.sock");
+        expect(result.uri).toBe("unix:///tmp/test-docker.sock");
+    });
+    it("returns non-unix DOCKER_HOST as-is (e.g. ssh://)", async () => {
+        process.env.DOCKER_HOST = "ssh://user@remote";
+        const { resolveDockerSocket } = await importFresh();
+        const result = resolveDockerSocket();
+        expect(result.socketPath).toBe("");
+        expect(result.uri).toBe("ssh://user@remote");
+    });
+    // ── Default socket path ────────────────────────────────────────────────
+    it("resolves /var/run/docker.sock symlink", async () => {
+        delete process.env.DOCKER_HOST;
+        vi.spyOn(fs, "realpathSync").mockImplementation((p) => {
+            if (String(p) === "/var/run/docker.sock") {
+                return "/Users/test/.orbstack/run/docker.sock";
+            }
+            throw new Error("ENOENT");
+        });
+        const { resolveDockerSocket } = await importFresh();
+        const result = resolveDockerSocket();
+        expect(result.socketPath).toBe("/Users/test/.orbstack/run/docker.sock");
+        expect(result.uri).toBe("unix:///Users/test/.orbstack/run/docker.sock");
+    });
+    // ── Docker context fallback ─────────────────────────────────────────────
+    it("falls back to docker context inspect when default socket missing", async () => {
+        delete process.env.DOCKER_HOST;
+        vi.spyOn(fs, "realpathSync").mockImplementation(() => {
+            throw new Error("ENOENT");
+        });
+        vi.spyOn(fs, "existsSync").mockImplementation((p) => {
+            return String(p) === "/Users/test/.docker/run/docker.sock";
+        });
+        mockedExecSync.mockReturnValue(JSON.stringify([
+            {
+                Endpoints: {
+                    docker: { Host: "unix:///Users/test/.docker/run/docker.sock" },
+                },
+            },
+        ]));
+        const { resolveDockerSocket } = await importFresh();
+        const result = resolveDockerSocket();
+        expect(result.socketPath).toBe("/Users/test/.docker/run/docker.sock");
+    });
+    // ── macOS provider fallback ──────────────────────────────────────────────
+    it("checks well-known macOS provider sockets when context fails", async () => {
+        delete process.env.DOCKER_HOST;
+        vi.spyOn(fs, "realpathSync").mockImplementation(() => {
+            throw new Error("ENOENT");
+        });
+        mockedExecSync.mockImplementation(() => {
+            throw new Error("docker not found");
+        });
+        const home = os.homedir();
+        vi.spyOn(fs, "existsSync").mockImplementation((p) => {
+            return String(p) === `${home}/.docker/run/docker.sock`;
+        });
+        // Ensure we're on darwin for this path
+        vi.spyOn(process, "platform", "get").mockReturnValue("darwin");
+        const { resolveDockerSocket } = await importFresh();
+        const result = resolveDockerSocket();
+        expect(result.socketPath).toBe(`${home}/.docker/run/docker.sock`);
+    });
+    // ── Reproduction: symlink missing → clear error ─────────────────────────
+    it("throws with actionable error when no socket is found", async () => {
+        delete process.env.DOCKER_HOST;
+        vi.spyOn(fs, "realpathSync").mockImplementation(() => {
+            throw new Error("ENOENT");
+        });
+        vi.spyOn(fs, "existsSync").mockReturnValue(false);
+        mockedExecSync.mockImplementation(() => {
+            throw new Error("docker not found");
+        });
+        vi.spyOn(process, "platform", "get").mockReturnValue("darwin");
+        const { resolveDockerSocket } = await importFresh();
+        expect(() => resolveDockerSocket()).toThrow("Could not find a Docker socket");
+        expect(() => resolveDockerSocket()).toThrow("DOCKER_HOST");
+        expect(() => resolveDockerSocket()).toThrow("ln -s");
+    });
+    it("falls through when DOCKER_HOST points to non-existent socket", async () => {
+        process.env.DOCKER_HOST = "unix:///nonexistent/docker.sock";
+        vi.spyOn(fs, "realpathSync").mockImplementation(() => {
+            throw new Error("ENOENT");
+        });
+        vi.spyOn(fs, "existsSync").mockReturnValue(false);
+        mockedExecSync.mockImplementation(() => {
+            throw new Error("docker not found");
+        });
+        vi.spyOn(process, "platform", "get").mockReturnValue("darwin");
+        const { resolveDockerSocket } = await importFresh();
+        expect(() => resolveDockerSocket()).toThrow("Could not find a Docker socket");
+    });
+});