@redwoodjs/agent-ci 0.8.0 → 0.8.2

package/README.md

@@ -64,13 +64,15 @@ When using a remote daemon (`DOCKER_HOST=ssh://...`), `host-gateway` resolves re
 
 Run GitHub Actions workflow jobs locally.
 
-| Flag                 | Short | Description                                                                       |
-| -------------------- | ----- | --------------------------------------------------------------------------------- |
-| `--workflow <path>`  | `-w`  | Path to the workflow file                                                         |
-| `--all`              | `-a`  | Discover and run all relevant workflows for the current branch                    |
-| `--pause-on-failure` | `-p`  | Pause on step failure for interactive debugging                                   |
-| `--quiet`            | `-q`  | Suppress animated rendering (also enabled by `AI_AGENT=1`)                        |
-| `--no-matrix`        |       | Collapse all matrix combinations into a single job (uses first value of each key) |
+| Flag                       | Short | Description                                                                                                                                                  |
+| -------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `--workflow <path>`        | `-w`  | Path to the workflow file                                                                                                                                    |
+| `--all`                    | `-a`  | Discover and run all relevant workflows for the current branch                                                                                               |
+| `--pause-on-failure`       | `-p`  | Pause on step failure for interactive debugging                                                                                                              |
+| `--quiet`                  | `-q`  | Suppress animated rendering (also enabled by `AI_AGENT=1`)                                                                                                   |
+| `--no-matrix`              |       | Collapse all matrix combinations into a single job (uses first value of each key)                                                                            |
+| `--github-token [<token>]` |       | GitHub token for fetching remote reusable workflows (auto-resolves via `gh auth token` if no value given). Also available as `AGENT_CI_GITHUB_TOKEN` env var |
+| `--commit-status`          |       | Post a GitHub commit status after the run (requires `--github-token`)                                                                                        |
 
 ### `agent-ci retry`
 

package/dist/cli.js

@@ -12,7 +12,7 @@ import { resolveJobOutputs } from "./runner/result-builder.js";
 import { createConcurrencyLimiter, getDefaultMaxConcurrentJobs } from "./output/concurrency.js";
 import { isWarmNodeModules, computeLockfileHash } from "./output/cleanup.js";
 import { getWorkingDirectory } from "./output/working-directory.js";
-import { pruneOrphanedDockerResources } from "./docker/shutdown.js";
+import { pruneOrphanedDockerResources, killOrphanedContainers, pruneStaleWorkspaces, } from "./docker/shutdown.js";
 import { topoSort } from "./workflow/job-scheduler.js";
 import { expandReusableJobs } from "./workflow/reusable-workflow.js";
 import { prefetchRemoteWorkflows } from "./workflow/remote-workflow-fetch.js";
@@ -49,6 +49,8 @@ async function run() {
         let pauseOnFailure = false;
         let runAll = false;
         let noMatrix = false;
+        let githubToken;
+        let commitStatus = false;
         for (let i = 1; i < args.length; i++) {
             if ((args[i] === "--workflow" || args[i] === "-w") && args[i + 1]) {
                 workflow = args[i + 1];
@@ -66,10 +68,37 @@ async function run() {
             else if (args[i] === "--no-matrix") {
                 noMatrix = true;
             }
+            else if (args[i] === "--commit-status") {
+                commitStatus = true;
+            }
+            else if (args[i] === "--github-token") {
+                // If the next arg looks like a token value (not another flag), use it.
+                // Otherwise, auto-resolve via `gh auth token`.
+                if (args[i + 1] && !args[i + 1].startsWith("-")) {
+                    githubToken = args[i + 1];
+                    i++;
+                }
+                else {
+                    try {
+                        githubToken = execSync("gh auth token", {
+                            encoding: "utf-8",
+                            stdio: ["pipe", "pipe", "pipe"],
+                        }).trim();
+                    }
+                    catch {
+                        console.error("[Agent CI] Error: --github-token requires `gh` CLI to be installed and authenticated, or pass a token value: --github-token <value>");
+                        process.exit(1);
+                    }
+                }
+            }
             else if (!args[i].startsWith("-")) {
                 sha = args[i];
             }
         }
+        // Also accept AGENT_CI_GITHUB_TOKEN env var (CLI flag takes precedence)
+        if (!githubToken && process.env.AGENT_CI_GITHUB_TOKEN) {
+            githubToken = process.env.AGENT_CI_GITHUB_TOKEN;
+        }
         let workingDir = process.env.AGENT_CI_WORKING_DIR;
         if (workingDir) {
             if (!path.isAbsolute(workingDir)) {
@@ -131,11 +160,14 @@ async function run() {
                 sha,
                 pauseOnFailure,
                 noMatrix,
+                githubToken,
             });
             if (results.length > 0) {
                 printSummary(results);
             }
-            postCommitStatus(results, sha);
+            if (commitStatus) {
+                postCommitStatus(results, sha, githubToken);
+            }
             const anyFailed = results.length === 0 || results.some((r) => !r.succeeded);
             process.exit(anyFailed ? 1 : 0);
         }
@@ -166,11 +198,14 @@ async function run() {
             sha,
             pauseOnFailure,
             noMatrix,
+            githubToken,
         });
         if (results.length > 0) {
             printSummary(results);
         }
-        postCommitStatus(results, sha);
+        if (commitStatus) {
+            postCommitStatus(results, sha, githubToken);
+        }
         if (results.length === 0 || results.some((r) => !r.succeeded)) {
             process.exit(1);
         }
@@ -246,7 +281,7 @@ async function run() {
 // Single entry point for both `--workflow` and `--all`.
 // One workflow = --all with a single entry.
 async function runWorkflows(options) {
-    const { workflowPaths, sha, pauseOnFailure, noMatrix = false } = options;
+    const { workflowPaths, sha, pauseOnFailure, noMatrix = false, githubToken } = options;
     // Suppress EventEmitter MaxListenersExceeded warnings when running many
     // parallel jobs (each job adds SIGINT/SIGTERM listeners).
     process.setMaxListeners(0);
@@ -346,6 +381,7 @@ async function runWorkflows(options) {
                 pauseOnFailure,
                 noMatrix,
                 store,
+                githubToken,
             });
             allResults.push(...results);
         }
@@ -377,6 +413,7 @@ async function runWorkflows(options) {
                     noMatrix,
                     store,
                     baseRunNum: runNums[0],
+                    githubToken,
                 });
                 allResults.push(...firstResults);
                 const settled = await Promise.allSettled(workflowPaths.slice(1).map((wf, i) => handleWorkflow({
@@ -386,6 +423,7 @@ async function runWorkflows(options) {
                     noMatrix,
                     store,
                     baseRunNum: runNums[i + 1],
+                    githubToken,
                 })));
                 for (const s of settled) {
                     if (s.status === "fulfilled") {
@@ -404,6 +442,7 @@ async function runWorkflows(options) {
                     noMatrix,
                     store,
                     baseRunNum: runNums[i],
+                    githubToken,
                 })));
                 for (const s of settled) {
                     if (s.status === "fulfilled") {
@@ -438,7 +477,7 @@ async function runWorkflows(options) {
 // Processes a single workflow file: parses jobs, handles matrix expansion,
 // wave scheduling, warm-cache serialization, and concurrency limiting.
 async function handleWorkflow(options) {
-    const { sha, pauseOnFailure, noMatrix = false, store } = options;
+    const { sha, pauseOnFailure, noMatrix = false, store, githubToken } = options;
     let workflowPath = options.workflowPath;
     if (!fs.existsSync(workflowPath)) {
         throw new Error(`Workflow file not found: ${workflowPath}`);
@@ -458,7 +497,7 @@ async function handleWorkflow(options) {
     config.GITHUB_REPO = githubRepo;
     const [owner, name] = githubRepo.split("/");
     const remoteCacheDir = path.resolve(getWorkingDirectory(), "cache", "remote-workflows");
-    const remoteCache = await prefetchRemoteWorkflows(workflowPath, remoteCacheDir);
+    const remoteCache = await prefetchRemoteWorkflows(workflowPath, remoteCacheDir, githubToken);
     const expandedEntries = expandReusableJobs(workflowPath, repoRoot, remoteCache);
     if (expandedEntries.length === 0) {
         debugCli(`[Agent CI] No jobs found in workflow: ${path.basename(workflowPath)}`);
@@ -653,6 +692,8 @@ async function handleWorkflow(options) {
         return result;
     };
     pruneOrphanedDockerResources();
+    killOrphanedContainers();
+    pruneStaleWorkspaces(getWorkingDirectory(), 24 * 60 * 60 * 1000);
     const limiter = createConcurrencyLimiter(maxJobs);
     const allResults = [];
     // Accumulate job outputs across waves for needs.*.outputs.* resolution
@@ -877,6 +918,10 @@ function printUsage() {
     console.log("  -p, --pause-on-failure         Pause on step failure for interactive debugging");
     console.log("  -q, --quiet                   Suppress animated rendering (also enabled by AI_AGENT=1)");
     console.log("      --no-matrix               Collapse all matrix combinations into a single job (uses first value of each key)");
+    console.log("      --github-token [<token>]  GitHub token for fetching remote reusable workflows");
+    console.log("                                (auto-resolves via `gh auth token` if no value given)");
+    console.log("                                Or set: AGENT_CI_GITHUB_TOKEN env var");
+    console.log("      --commit-status           Post a GitHub commit status after the run (requires --github-token)");
 }
 function resolveRepoRoot() {
     let repoRoot = process.cwd();

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" });

package/dist/docker/container-config.js

@@ -33,7 +33,8 @@ 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, dockerSocketPath = "/var/run/docker.sock", } = opts;
+    const { hostWorkDir, shimsDir, signalsDir, diagDir, toolCacheDir, pnpmStoreDir, npmCacheDir, bunCacheDir, playwrightCacheDir, warmModulesDir, hostRunnerDir, useDirectContainer, githubRepo, dockerSocketPath = "/var/run/docker.sock", } = opts;
+    const repoName = githubRepo.split("/").pop() || "repo";
     const h = toHostPath;
     return [
         // When using a custom container, bind-mount the extracted runner
@@ -50,12 +51,11 @@ export function buildContainerBinds(opts) {
         ...(npmCacheDir ? [`${h(npmCacheDir)}:/home/runner/.npm`] : []),
         ...(bunCacheDir ? [`${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/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`,
+        // Warm node_modules: mounted directly at the workspace node_modules path
+        // so pnpm/esbuild path resolution sees a real directory (not a symlink).
+        // The git shim blocks `git clean` and checkout is patched with clean:false,
+        // so EBUSY on this bind mount is not a concern.
+        `${h(warmModulesDir)}:/home/runner/_work/${repoName}/${repoName}/node_modules`,
     ];
 }
 // ─── Container command ────────────────────────────────────────────────────────
@@ -89,7 +89,6 @@ 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/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

@@ -56,11 +56,12 @@ describe("buildContainerBinds", () => {
             warmModulesDir: "/tmp/warm",
             hostRunnerDir: "/tmp/runner",
             useDirectContainer: false,
+            githubRepo: "org/repo",
         });
         expect(binds).toContain("/tmp/work:/home/runner/_work");
         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/node_modules");
+        expect(binds).toContain("/tmp/warm:/home/runner/_work/repo/repo/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");
@@ -78,6 +79,7 @@ describe("buildContainerBinds", () => {
             warmModulesDir: "/tmp/warm",
             hostRunnerDir: "/tmp/runner",
             useDirectContainer: false,
+            githubRepo: "org/repo",
         });
         expect(binds).toContain("/tmp/work:/home/runner/_work");
         expect(binds.some((b) => b.includes(".pnpm-store"))).toBe(false);
@@ -96,6 +98,7 @@ describe("buildContainerBinds", () => {
             warmModulesDir: "/tmp/warm",
             hostRunnerDir: "/tmp/runner",
             useDirectContainer: false,
+            githubRepo: "org/repo",
         });
         expect(binds).toContain("/tmp/npm:/home/runner/.npm");
         expect(binds.some((b) => b.includes(".pnpm-store"))).toBe(false);
@@ -112,6 +115,7 @@ describe("buildContainerBinds", () => {
             warmModulesDir: "/tmp/warm",
             hostRunnerDir: "/tmp/runner",
             useDirectContainer: false,
+            githubRepo: "org/repo",
             dockerSocketPath: "/Users/test/.orbstack/run/docker.sock",
         });
         expect(binds).toContain("/Users/test/.orbstack/run/docker.sock:/var/run/docker.sock");
@@ -131,6 +135,7 @@ describe("buildContainerBinds", () => {
             warmModulesDir: "/tmp/warm",
             hostRunnerDir: "/tmp/runner",
             useDirectContainer: true,
+            githubRepo: "org/repo",
         });
         expect(binds).toContain("/tmp/runner:/home/runner");
     });
@@ -322,6 +327,7 @@ describe("buildContainerBinds with dockerSocketPath", () => {
         warmModulesDir: "/tmp/warm",
         hostRunnerDir: "/tmp/runner",
         useDirectContainer: false,
+        githubRepo: "org/repo",
     };
     it("uses default /var/run/docker.sock when no dockerSocketPath is provided", async () => {
         const { buildContainerBinds } = await import("./container-config.js");
@@ -352,6 +358,7 @@ describe("buildContainerBinds with signalsDir", () => {
         warmModulesDir: "/tmp/warm",
         hostRunnerDir: "/tmp/runner",
         useDirectContainer: false,
+        githubRepo: "org/repo",
     };
     it("includes signals bind-mount when signalsDir is provided", async () => {
         const { buildContainerBinds } = await import("./container-config.js");

package/dist/docker/docker-socket.js

@@ -105,13 +105,17 @@ export function resolveDockerSocket() {
     throw new Error(lines.join("\n"));
 }
 /**
- * If `socketPath` exists (following symlinks), return the real path.
- * Returns undefined otherwise.
+ * If `socketPath` exists (following symlinks) and is accessible, return the
+ * real path.  Returns undefined otherwise so the caller can keep searching.
  */
 function resolveIfExists(socketPath) {
     try {
         // fs.realpathSync follows symlinks and throws if the target doesn't exist
-        return fs.realpathSync(socketPath);
+        const resolved = fs.realpathSync(socketPath);
+        // Verify we can actually connect — the socket may exist but be owned by
+        // root:docker with 660 perms (common on Linux with Docker Desktop).
+        fs.accessSync(resolved, fs.constants.R_OK | fs.constants.W_OK);
+        return resolved;
     }
     catch {
         return undefined;

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

@@ -20,6 +20,7 @@ describe("resolveDockerSocket", () => {
     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");
+        vi.spyOn(fs, "accessSync").mockReturnValue(undefined);
         const { resolveDockerSocket } = await importFresh();
         const result = resolveDockerSocket();
         expect(result.socketPath).toBe("/tmp/test-docker.sock");
@@ -41,11 +42,36 @@ describe("resolveDockerSocket", () => {
             }
             throw new Error("ENOENT");
         });
+        vi.spyOn(fs, "accessSync").mockReturnValue(undefined);
         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");
     });
+    // ── EACCES fallthrough ─────────────────────────────────────────────────
+    it("falls through to docker context when default socket is not accessible", async () => {
+        delete process.env.DOCKER_HOST;
+        // Socket exists but is not accessible (e.g. root:docker 660 on Linux)
+        vi.spyOn(fs, "realpathSync").mockReturnValue("/var/run/docker.sock");
+        vi.spyOn(fs, "accessSync").mockImplementation(() => {
+            throw Object.assign(new Error("EACCES"), { code: "EACCES" });
+        });
+        vi.spyOn(fs, "existsSync").mockImplementation((p) => {
+            return String(p) === "/home/user/.docker/desktop/docker.sock";
+        });
+        mockedExecSync.mockReturnValue(JSON.stringify([
+            {
+                Endpoints: {
+                    docker: {
+                        Host: "unix:///home/user/.docker/desktop/docker.sock",
+                    },
+                },
+            },
+        ]));
+        const { resolveDockerSocket } = await importFresh();
+        const result = resolveDockerSocket();
+        expect(result.socketPath).toBe("/home/user/.docker/desktop/docker.sock");
+    });
     // ── Docker context fallback ─────────────────────────────────────────────
     it("falls back to docker context inspect when default socket missing", async () => {
         delete process.env.DOCKER_HOST;

package/dist/docker/shutdown.js

@@ -101,6 +101,49 @@ export function pruneOrphanedDockerResources() {
         // Docker not reachable — skip
     }
 }
+// ─── Orphaned container cleanup ───────────────────────────────────────────────
+/**
+ * Find and kill running `agent-ci-*` containers whose parent process is dead.
+ *
+ * Every container created by `executeLocalJob` is labelled with
+ * `agent-ci.pid=<PID>`. If the process that spawned the container is no
+ * longer alive, the container is an orphan and should be killed — along with
+ * its svc-* sidecars and bridge network (via `killRunnerContainers`).
+ *
+ * Containers without the label (created before this feature) are skipped.
+ */
+export function killOrphanedContainers() {
+    let lines;
+    try {
+        // Format: "containerId containerName pid-label"
+        const raw = execSync(`docker ps --filter "name=agent-ci-" --filter "status=running" --format "{{.ID}} {{.Names}} {{.Label \\"agent-ci.pid\\"}}"`, { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+        if (!raw) {
+            return;
+        }
+        lines = raw.split("\n");
+    }
+    catch {
+        // Docker not reachable — skip
+        return;
+    }
+    for (const line of lines) {
+        const [, containerName, pidStr] = line.split(" ");
+        if (!containerName || !pidStr) {
+            continue;
+        }
+        const pid = Number(pidStr);
+        if (!Number.isFinite(pid) || pid <= 0) {
+            continue;
+        }
+        try {
+            process.kill(pid, 0); // signal 0 = liveness check, throws if dead
+        }
+        catch {
+            // Parent is dead — this container is an orphan.
+            killRunnerContainers(containerName);
+        }
+    }
+}
 // ─── Workspace pruning ────────────────────────────────────────────────────────
 /**
  * Remove stale `agent-ci-*` run directories older than `maxAgeMs` from

package/dist/docker/shutdown.test.js

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
@@ -92,6 +92,78 @@ describe("Stale workspace pruning", () => {
         expect(fs.existsSync(otherDir)).toBe(true);
     });
 });
+// ── Orphaned container cleanup ────────────────────────────────────────────────
+describe("killOrphanedContainers", () => {
+    const execSyncMock = vi.fn();
+    const killSpy = vi.spyOn(process, "kill");
+    beforeEach(() => {
+        vi.resetModules();
+        vi.doMock("node:child_process", () => ({
+            execSync: execSyncMock,
+        }));
+        execSyncMock.mockReset();
+        killSpy.mockReset();
+    });
+    afterEach(() => {
+        killSpy.mockRestore();
+    });
+    it("kills containers whose parent PID is dead", async () => {
+        execSyncMock.mockImplementation((cmd) => {
+            if (cmd.startsWith("docker ps")) {
+                return "abc123 agent-ci-runner-1 99999\n";
+            }
+            return "";
+        });
+        killSpy.mockImplementation(((pid, signal) => {
+            if (signal === 0 && pid === 99999) {
+                throw new Error("ESRCH");
+            }
+            return true;
+        }));
+        const { killOrphanedContainers } = await import("./shutdown.js");
+        killOrphanedContainers();
+        const rmCalls = execSyncMock.mock.calls.filter(([cmd]) => cmd.includes("docker rm -f agent-ci-runner-1"));
+        expect(rmCalls.length).toBeGreaterThan(0);
+    });
+    it("leaves containers whose parent PID is alive", async () => {
+        const myPid = process.pid;
+        execSyncMock.mockImplementation((cmd) => {
+            if (cmd.startsWith("docker ps")) {
+                return `abc123 agent-ci-runner-2 ${myPid}\n`;
+            }
+            return "";
+        });
+        killSpy.mockImplementation(((pid, signal) => {
+            if (signal === 0 && pid === myPid) {
+                return true;
+            }
+            throw new Error("ESRCH");
+        }));
+        const { killOrphanedContainers } = await import("./shutdown.js");
+        killOrphanedContainers();
+        const rmCalls = execSyncMock.mock.calls.filter(([cmd]) => cmd.includes("docker rm -f"));
+        expect(rmCalls).toEqual([]);
+    });
+    it("skips containers without a PID label", async () => {
+        execSyncMock.mockImplementation((cmd) => {
+            if (cmd.startsWith("docker ps")) {
+                return "abc123 agent-ci-runner-3 \n";
+            }
+            return "";
+        });
+        const { killOrphanedContainers } = await import("./shutdown.js");
+        killOrphanedContainers();
+        const rmCalls = execSyncMock.mock.calls.filter(([cmd]) => cmd.includes("docker rm -f"));
+        expect(rmCalls).toEqual([]);
+    });
+    it("handles Docker not reachable gracefully", async () => {
+        execSyncMock.mockImplementation(() => {
+            throw new Error("Cannot connect to Docker daemon");
+        });
+        const { killOrphanedContainers } = await import("./shutdown.js");
+        expect(() => killOrphanedContainers()).not.toThrow();
+    });
+});
 describe("containerWorkDir cleanup on exit", () => {
     let tmpDir;
     beforeEach(() => {

package/dist/runner/directory-setup.test.js

@@ -149,6 +149,7 @@ describe("buildContainerBinds — PM-scoped mounts", () => {
             warmModulesDir: "/tmp/warm",
             hostRunnerDir: "/tmp/runner",
             useDirectContainer: false,
+            githubRepo: "org/repo",
         });
         expect(binds).toContain("/tmp/npm-cache:/home/runner/.npm");
         expect(binds.some((b) => b.includes(".pnpm-store"))).toBe(false);
@@ -167,6 +168,7 @@ describe("buildContainerBinds — PM-scoped mounts", () => {
             warmModulesDir: "/tmp/warm",
             hostRunnerDir: "/tmp/runner",
             useDirectContainer: false,
+            githubRepo: "org/repo",
         });
         expect(binds).toContain("/tmp/pnpm-store:/home/runner/_work/.pnpm-store");
         expect(binds.some((b) => b.includes("/.npm"))).toBe(false);
@@ -185,6 +187,7 @@ describe("buildContainerBinds — PM-scoped mounts", () => {
             warmModulesDir: "/tmp/warm",
             hostRunnerDir: "/tmp/runner",
             useDirectContainer: false,
+            githubRepo: "org/repo",
         });
         expect(binds).toContain("/tmp/bun-cache:/home/runner/.bun/install/cache");
         expect(binds.some((b) => b.includes(".pnpm-store"))).toBe(false);
@@ -202,6 +205,7 @@ describe("buildContainerBinds — PM-scoped mounts", () => {
             warmModulesDir: "/tmp/warm",
             hostRunnerDir: "/tmp/runner",
             useDirectContainer: false,
+            githubRepo: "org/repo",
         });
         expect(binds.some((b) => b.includes(".pnpm-store"))).toBe(false);
         expect(binds.some((b) => b.includes("/.npm"))).toBe(false);

package/dist/runner/git-shim.js

@@ -1,13 +1,5 @@
 import path from "path";
 import fs from "fs";
-// ─── Fake SHA computation ─────────────────────────────────────────────────────
-/**
- * Resolve which SHA the git shim should return for ls-remote / rev-parse.
- * Uses the real SHA if provided, otherwise falls back to a deterministic fake.
- */
-export function computeFakeSha(headSha) {
-    return headSha && headSha !== "HEAD" ? headSha : "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
-}
 // ─── Git shim script ──────────────────────────────────────────────────────────
 /**
  * Write the bash git shim to `<shimsDir>/git`.

package/dist/runner/git-shim.test.js

@@ -2,21 +2,6 @@ import { describe, it, expect, beforeEach, afterEach } from "vitest";
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
-// ── computeFakeSha ────────────────────────────────────────────────────────────
-describe("computeFakeSha", () => {
-    it("returns the headSha when it is a real SHA", async () => {
-        const { computeFakeSha } = await import("./git-shim.js");
-        expect(computeFakeSha("abc123def456")).toBe("abc123def456");
-    });
-    it("returns the deterministic fake when headSha is HEAD", async () => {
-        const { computeFakeSha } = await import("./git-shim.js");
-        expect(computeFakeSha("HEAD")).toBe("aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa");
-    });
-    it("returns the deterministic fake when headSha is undefined", async () => {
-        const { computeFakeSha } = await import("./git-shim.js");
-        expect(computeFakeSha(undefined)).toBe("aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa");
-    });
-});
 // ── writeGitShim ──────────────────────────────────────────────────────────────
 describe("writeGitShim", () => {
     let tmpDir;

package/dist/runner/local-job.js

@@ -12,7 +12,7 @@ import { killRunnerContainers } from "../docker/shutdown.js";
 import { startEphemeralDtu } from "dtu-github-actions/ephemeral";
 import { tailLogFile } from "../output/reporter.js";
 import { writeJobMetadata } from "./metadata.js";
-import { computeFakeSha, writeGitShim } from "./git-shim.js";
+import { writeGitShim } from "./git-shim.js";
 import { prepareWorkspace } from "./workspace.js";
 import { createRunDirectories } from "./directory-setup.js";
 import { buildContainerEnv, buildContainerBinds, buildContainerCmd, resolveDtuHost, resolveDockerApiUrl, resolveDockerExtraHosts, } from "../docker/container-config.js";
@@ -184,13 +184,23 @@ export async function executeLocalJob(job, options) {
     writeJobMetadata({ logDir, containerName, job });
     // Open debug stream to capture raw container output
     const debugStream = fs.createWriteStream(debugLogPath);
+    // Hoisted for cleanup in `finally` — assigned inside the try block.
+    let container = null;
+    let serviceCtx;
+    const hostRunnerDir = path.resolve(runDir, "runner");
     // Signal handler: ensure cleanup runs even when killed.
     // Do NOT call process.exit() here — multiple jobs register handlers concurrently,
     // and an early exit would prevent other jobs' handlers from cleaning up their containers.
     // killRunnerContainers already handles the runner, its svc-* sidecars, and the network.
     const signalCleanup = () => {
         killRunnerContainers(containerName);
-        for (const d of [dirs.containerWorkDir, dirs.shimsDir, dirs.signalsDir, dirs.diagDir]) {
+        for (const d of [
+            dirs.containerWorkDir,
+            dirs.shimsDir,
+            dirs.signalsDir,
+            dirs.diagDir,
+            hostRunnerDir,
+        ]) {
             try {
                 fs.rmSync(d, { recursive: true, force: true });
             }
@@ -199,10 +209,6 @@ export async function executeLocalJob(job, options) {
     };
     process.on("SIGINT", signalCleanup);
     process.on("SIGTERM", signalCleanup);
-    // Hoisted for cleanup in `finally` — assigned inside the try block.
-    let container = null;
-    let serviceCtx;
-    const hostRunnerDir = path.resolve(runDir, "runner");
     try {
         // 1. Seed the job to Local DTU
         const [githubOwner, githubRepoName] = (job.githubRepo || "").split("/");
@@ -243,8 +249,7 @@ export async function executeLocalJob(job, options) {
         // 4. Write git shim BEFORE container start so the entrypoint can install it
         // immediately. On Linux, prepareWorkspace (rsync) is slow enough that the
         // container entrypoint would race ahead and find an empty shims dir.
-        const fakeSha = computeFakeSha(job.headSha);
-        writeGitShim(dirs.shimsDir, fakeSha);
+        writeGitShim(dirs.shimsDir, job.realHeadSha);
         // Prepare workspace files in parallel with container setup
         const workspacePrepStart = Date.now();
         const workspacePrepPromise = (async () => {
@@ -449,6 +454,7 @@ export async function executeLocalJob(job, options) {
             warmModulesDir: dirs.warmModulesDir,
             hostRunnerDir,
             useDirectContainer,
+            githubRepo,
             dockerSocketPath: getDockerSocket().socketPath || undefined,
         });
         const containerCmd = buildContainerCmd({
@@ -463,6 +469,9 @@ export async function executeLocalJob(job, options) {
         container = await getDocker().createContainer({
             Image: containerImage,
             name: containerName,
+            Labels: {
+                "agent-ci.pid": String(process.pid),
+            },
             Env: containerEnv,
             ...(useDirectContainer ? { Entrypoint: ["bash"] } : {}),
             Cmd: containerCmd,

package/dist/workflow/remote-workflow-fetch.js

@@ -1,6 +1,5 @@
 import fs from "node:fs";
 import path from "node:path";
-import { execSync } from "node:child_process";
 import { parse as parseYaml } from "yaml";
 /**
  * Parse a remote reusable workflow ref string.
@@ -37,27 +36,6 @@ export function remoteCachePath(cacheDir, ref) {
     const sanitizedRef = ref.ref.replace(/[^a-zA-Z0-9._-]/g, "-");
     return path.join(cacheDir, `${ref.owner}__${ref.repo}@${sanitizedRef}`, ref.path);
 }
-/**
- * Resolve a GitHub token for API access.
- * Tries `gh auth token` first (real user credentials), then falls back to
- * GITHUB_TOKEN env var. This ordering matters because agent-ci injects a
- * fake token as GITHUB_TOKEN for the runner context.
- */
-function resolveGitHubToken() {
-    try {
-        const token = execSync("gh auth token", {
-            encoding: "utf-8",
-            stdio: ["pipe", "pipe", "pipe"],
-        }).trim();
-        if (token) {
-            return token;
-        }
-    }
-    catch {
-        // gh not installed or not authenticated
-    }
-    return process.env.GITHUB_TOKEN || null;
-}
 /**
  * Scan a workflow YAML and prefetch all remote reusable workflow refs.
  * Downloaded files are written to cacheDir.
@@ -65,9 +43,11 @@ function resolveGitHubToken() {
  * - SHA refs: cached forever (immutable)
  * - Tag/branch refs: always re-fetched (mutable)
  *
- * Throws on fetch failures (404, auth errors, network errors).
+ * Authentication is opt-in via the `githubToken` parameter.
+ * Public repos may work without auth (within rate limits).
+ * On 401/403 responses, throws with instructions for how to authenticate.
  */
-export async function prefetchRemoteWorkflows(workflowPath, cacheDir) {
+export async function prefetchRemoteWorkflows(workflowPath, cacheDir, githubToken) {
     const resolved = new Map();
     const raw = parseYaml(fs.readFileSync(workflowPath, "utf-8"));
     const jobs = raw?.jobs ?? {};
@@ -84,7 +64,6 @@ export async function prefetchRemoteWorkflows(workflowPath, cacheDir) {
     if (remoteRefs.length === 0) {
         return resolved;
     }
-    const token = resolveGitHubToken();
     const errors = [];
     await Promise.all(remoteRefs.map(async (ref) => {
         const dest = remoteCachePath(cacheDir, ref);
@@ -99,13 +78,13 @@ export async function prefetchRemoteWorkflows(workflowPath, cacheDir) {
                 Accept: "application/vnd.github.v3+json",
                 "User-Agent": "agent-ci/1.0",
             };
-            if (token) {
-                headers["Authorization"] = `token ${token}`;
+            if (githubToken) {
+                headers["Authorization"] = `token ${githubToken}`;
             }
             const response = await fetch(url, { headers });
             if (!response.ok) {
                 const hint = response.status === 401 || response.status === 403
-                    ? " Ensure GITHUB_TOKEN is set or run `gh auth login`."
+                    ? ` Run with: agent-ci run --github-token\n  Or set: export AGENT_CI_GITHUB_TOKEN=$(gh auth token)`
                     : "";
                 errors.push(`Failed to fetch remote workflow ${ref.raw} (HTTP ${response.status}).${hint}`);
                 return;

package/dist/workflow/remote-workflow-fetch.test.js

@@ -196,7 +196,84 @@ jobs:
   lint:
     uses: org/private-repo/.github/workflows/lint.yml@v1
 `);
-        await expect(prefetchRemoteWorkflows(wf, cacheDir)).rejects.toThrow(/gh auth login/);
+        await expect(prefetchRemoteWorkflows(wf, cacheDir)).rejects.toThrow(/--github-token/);
+    });
+    it("sends Authorization header when githubToken is provided", async () => {
+        const remoteYaml = `
+on: workflow_call
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo lint
+`;
+        mockFetchSuccess(remoteYaml);
+        const wf = writeWorkflow(`
+jobs:
+  lint:
+    uses: org/repo/.github/workflows/lint.yml@v1
+`);
+        await prefetchRemoteWorkflows(wf, cacheDir, "ghp_test123");
+        const fetchCall = globalThis.fetch.mock.calls[0];
+        expect(fetchCall[1].headers["Authorization"]).toBe("token ghp_test123");
+    });
+    it("does not send Authorization header when no token provided", async () => {
+        const remoteYaml = `
+on: workflow_call
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo lint
+`;
+        mockFetchSuccess(remoteYaml);
+        const wf = writeWorkflow(`
+jobs:
+  lint:
+    uses: org/repo/.github/workflows/lint.yml@v1
+`);
+        await prefetchRemoteWorkflows(wf, cacheDir);
+        const fetchCall = globalThis.fetch.mock.calls[0];
+        expect(fetchCall[1].headers["Authorization"]).toBeUndefined();
+    });
+    it("throws on 403 with auth hint mentioning --github-token and AGENT_CI_GITHUB_TOKEN", async () => {
+        globalThis.fetch = vi.fn().mockResolvedValue({
+            ok: false,
+            status: 403,
+        });
+        const wf = writeWorkflow(`
+jobs:
+  lint:
+    uses: org/private-repo/.github/workflows/lint.yml@v1
+`);
+        await expect(prefetchRemoteWorkflows(wf, cacheDir)).rejects.toThrow(/--github-token/);
+        await expect(prefetchRemoteWorkflows(wf, cacheDir)).rejects.toThrow(/AGENT_CI_GITHUB_TOKEN/);
+    });
+    it("succeeds fetching a public remote workflow without auth", async () => {
+        const remoteYaml = `
+on: workflow_call
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo lint
+`;
+        mockFetchSuccess(remoteYaml);
+        const wf = writeWorkflow(`
+jobs:
+  lint:
+    uses: org/public-repo/.github/workflows/lint.yml@v1
+`);
+        // No githubToken passed — simulates public repo access without auth
+        const result = await prefetchRemoteWorkflows(wf, cacheDir);
+        expect(result.size).toBe(1);
+        // Verify no Authorization header was sent
+        const fetchCall = globalThis.fetch.mock.calls[0];
+        expect(fetchCall[1].headers["Authorization"]).toBeUndefined();
+        // Verify the cached file was written correctly
+        const cachedPath = result.get("org/public-repo/.github/workflows/lint.yml@v1");
+        expect(fs.existsSync(cachedPath)).toBe(true);
+        expect(fs.readFileSync(cachedPath, "utf-8")).toBe(remoteYaml);
     });
     it("fetches multiple remote refs in parallel", async () => {
         const remoteYaml = `

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redwoodjs/agent-ci",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Local GitHub Actions runner — pause on failure, ~0ms cache, official runner binary. Built for AI coding agents.",
   "keywords": [
     "act-alternative",
@@ -40,7 +40,7 @@
     "log-update": "^7.2.0",
     "minimatch": "^10.2.1",
     "yaml": "^2.8.2",
-    "dtu-github-actions": "0.8.0"
+    "dtu-github-actions": "0.8.2"
   },
   "devDependencies": {
     "@types/dockerode": "^3.3.34",