@redwoodjs/agent-ci 0.8.1 → 0.9.0

package/dist/cli.js

@@ -7,17 +7,18 @@ import { getNextLogNum } from "./output/logger.js";
 import { setWorkingDirectory, DEFAULT_WORKING_DIR, PROJECT_ROOT, } from "./output/working-directory.js";
 import { debugCli } from "./output/debug.js";
 import { executeLocalJob } from "./runner/local-job.js";
-import { parseWorkflowSteps, parseWorkflowServices, parseWorkflowContainer, validateSecrets, parseMatrixDef, expandMatrixCombinations, collapseMatrixToSingle, isWorkflowRelevant, getChangedFiles, parseJobOutputDefs, parseJobIf, evaluateJobIf, parseFailFast, expandExpressions, } from "./workflow/workflow-parser.js";
+import { parseWorkflowSteps, parseWorkflowServices, parseWorkflowContainer, validateSecrets, extractSecretRefs, parseMatrixDef, expandMatrixCombinations, collapseMatrixToSingle, isWorkflowRelevant, getChangedFiles, parseJobOutputDefs, parseJobIf, evaluateJobIf, parseFailFast, expandExpressions, } from "./workflow/workflow-parser.js";
 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";
 import { printSummary } from "./output/reporter.js";
 import { syncWorkspaceForRetry } from "./runner/sync.js";
+import { computeDirtySha } from "./runner/dirty-sha.js";
 import { RunStateStore } from "./output/run-state.js";
 import { renderRunState } from "./output/state-renderer.js";
 import { isAgentMode, setQuietMode } from "./output/agent-mode.js";
@@ -489,9 +490,12 @@ async function handleWorkflow(options) {
     const { headSha, shaRef } = sha
         ? resolveHeadSha(repoRoot, sha)
         : { headSha: undefined, shaRef: undefined };
-    // Always resolve the real HEAD SHA for the push event context (before/after).
-    // This is separate from headSha which may be undefined for dirty workspace copies.
-    const realHeadSha = headSha ?? resolveHeadSha(repoRoot, "HEAD").headSha;
+    // Always resolve a SHA that represents the code being executed.
+    // When the working tree is dirty and no explicit --sha was given, compute an
+    // ephemeral commit SHA that captures the dirty state (including untracked files).
+    // This is purely informational — actions/checkout is always stubbed, so no
+    // workflow will ever try to fetch this SHA from a remote.
+    const realHeadSha = headSha ?? computeDirtySha(repoRoot) ?? resolveHeadSha(repoRoot, "HEAD").headSha;
     const baseSha = resolveBaseSha(repoRoot, realHeadSha);
     const githubRepo = config.GITHUB_REPO ?? resolveRepoSlug(repoRoot);
     config.GITHUB_REPO = githubRepo;
@@ -546,7 +550,11 @@ async function handleWorkflow(options) {
     if (expandedJobs.length === 1) {
         const ej = expandedJobs[0];
         const actualTaskName = ej.sourceTaskName ?? ej.taskName;
-        const secrets = loadMachineSecrets(repoRoot);
+        const requiredRefs = extractSecretRefs(ej.workflowPath, actualTaskName);
+        const secrets = loadMachineSecrets(repoRoot, requiredRefs);
+        if (githubToken && !secrets["GITHUB_TOKEN"]) {
+            secrets["GITHUB_TOKEN"] = githubToken;
+        }
         const secretsFilePath = path.join(repoRoot, ".env.agent-ci");
         validateSecrets(ej.workflowPath, actualTaskName, secrets, secretsFilePath);
         // Resolve inputs for called workflow jobs
@@ -608,7 +616,11 @@ async function handleWorkflow(options) {
     let globalIdx = 0;
     const buildJob = (ej) => {
         const actualTaskName = ej.sourceTaskName ?? ej.taskName;
-        const secrets = loadMachineSecrets(repoRoot);
+        const requiredRefs = extractSecretRefs(ej.workflowPath, actualTaskName);
+        const secrets = loadMachineSecrets(repoRoot, requiredRefs);
+        if (githubToken && !secrets["GITHUB_TOKEN"]) {
+            secrets["GITHUB_TOKEN"] = githubToken;
+        }
         const secretsFilePath = path.join(repoRoot, ".env.agent-ci");
         validateSecrets(ej.workflowPath, actualTaskName, secrets, secretsFilePath);
         const idx = globalIdx++;
@@ -668,7 +680,11 @@ async function handleWorkflow(options) {
         const { taskName, matrixContext } = ej;
         const actualTaskName = ej.sourceTaskName ?? taskName;
         debugCli(`Running: ${path.basename(ej.workflowPath)} | Task: ${taskName}${matrixContext ? ` | Matrix: ${JSON.stringify(Object.fromEntries(Object.entries(matrixContext).filter(([k]) => !k.startsWith("__"))))}` : ""}`);
-        const secrets = loadMachineSecrets(repoRoot);
+        const requiredRefs = extractSecretRefs(ej.workflowPath, actualTaskName);
+        const secrets = loadMachineSecrets(repoRoot, requiredRefs);
+        if (githubToken && !secrets["GITHUB_TOKEN"]) {
+            secrets["GITHUB_TOKEN"] = githubToken;
+        }
         const secretsFilePath = path.join(repoRoot, ".env.agent-ci");
         validateSecrets(ej.workflowPath, actualTaskName, secrets, secretsFilePath);
         const inputsContext = resolveInputsForJob(ej, secrets, needsContext);
@@ -692,6 +708,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
@@ -833,6 +851,7 @@ async function handleWorkflow(options) {
         collectOutputs(result, ej.taskName);
         return result;
     };
+    const seenErrorMessages = new Set();
     for (let wi = 0; wi < filteredWaves.length; wi++) {
         const waveJobIds = new Set(filteredWaves[wi]);
         const waveJobs = expandedJobs.filter((j) => waveJobIds.has(j.taskName));
@@ -854,8 +873,11 @@ async function handleWorkflow(options) {
                 else {
                     const taskName = isJobError(r.reason) ? r.reason.taskName : "unknown";
                     const errorMessage = isJobError(r.reason) ? r.reason.message : String(r.reason);
-                    console.error(`\n[Agent CI] Job failed with error: ${taskName}`);
-                    console.error(`  Error: ${errorMessage}`);
+                    if (!seenErrorMessages.has(errorMessage)) {
+                        seenErrorMessages.add(errorMessage);
+                        console.error(`\n[Agent CI] Job failed with error: ${taskName}`);
+                        console.error(`  Error: ${errorMessage}`);
+                    }
                     allResults.push(createFailedJobResult(taskName, workflowPath, r.reason));
                 }
             }
@@ -872,8 +894,11 @@ async function handleWorkflow(options) {
                 else {
                     const taskName = isJobError(r.reason) ? r.reason.taskName : "unknown";
                     const errorMessage = isJobError(r.reason) ? r.reason.message : String(r.reason);
-                    console.error(`\n[Agent CI] Job failed with error: ${taskName}`);
-                    console.error(`  Error: ${errorMessage}`);
+                    if (!seenErrorMessages.has(errorMessage)) {
+                        seenErrorMessages.add(errorMessage);
+                        console.error(`\n[Agent CI] Job failed with error: ${taskName}`);
+                        console.error(`  Error: ${errorMessage}`);
+                    }
                     allResults.push(createFailedJobResult(taskName, workflowPath, r.reason));
                 }
             }
@@ -920,6 +945,12 @@ function printUsage() {
     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)");
+    console.log("");
+    console.log("Secrets:");
+    console.log("  Workflow secrets (${{ secrets.FOO }}) are resolved from:");
+    console.log("    1. .env.agent-ci file in the repo root");
+    console.log("    2. Environment variables (shell env acts as fallback)");
+    console.log("    3. --github-token automatically provides secrets.GITHUB_TOKEN");
 }
 function resolveRepoRoot() {
     let repoRoot = process.cwd();

package/dist/config.js

@@ -55,35 +55,47 @@ export const config = {
     GITHUB_API_URL: process.env.GITHUB_API_URL || "http://localhost:8910",
 };
 /**
- * Load machine-local secrets from `.env.machine` at the agent-ci project root.
+ * Load machine-local secrets from `.env.agent-ci` at the given base directory.
  * The file uses KEY=VALUE syntax (lines starting with # are ignored).
- * Returns an empty object if the file doesn't exist.
+ *
+ * When `envFallbackKeys` is provided, any key in that list that is NOT already
+ * present in the file will be filled from `process.env` (shell environment
+ * variables act as a fallback for the .env file).
+ *
+ * Returns an empty object if the file doesn't exist and no env fallbacks match.
  */
-export function loadMachineSecrets(baseDir) {
+export function loadMachineSecrets(baseDir, envFallbackKeys) {
     const envMachinePath = path.join(baseDir ?? PROJECT_ROOT, ".env.agent-ci");
-    if (!fs.existsSync(envMachinePath)) {
-        return {};
-    }
     const secrets = {};
-    const lines = fs.readFileSync(envMachinePath, "utf-8").split("\n");
-    for (const line of lines) {
-        const trimmed = line.trim();
-        if (!trimmed || trimmed.startsWith("#")) {
-            continue;
-        }
-        const eqIdx = trimmed.indexOf("=");
-        if (eqIdx < 1) {
-            continue;
-        }
-        const key = trimmed.slice(0, eqIdx).trim();
-        let value = trimmed.slice(eqIdx + 1).trim();
-        // Strip optional surrounding quotes
-        if ((value.startsWith('"') && value.endsWith('"')) ||
-            (value.startsWith("'") && value.endsWith("'"))) {
-            value = value.slice(1, -1);
+    if (fs.existsSync(envMachinePath)) {
+        const lines = fs.readFileSync(envMachinePath, "utf-8").split("\n");
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith("#")) {
+                continue;
+            }
+            const eqIdx = trimmed.indexOf("=");
+            if (eqIdx < 1) {
+                continue;
+            }
+            const key = trimmed.slice(0, eqIdx).trim();
+            let value = trimmed.slice(eqIdx + 1).trim();
+            // Strip optional surrounding quotes
+            if ((value.startsWith('"') && value.endsWith('"')) ||
+                (value.startsWith("'") && value.endsWith("'"))) {
+                value = value.slice(1, -1);
+            }
+            if (key) {
+                secrets[key] = value;
+            }
         }
-        if (key) {
-            secrets[key] = value;
+    }
+    // Fill missing secrets from process.env (shell env vars act as fallback)
+    if (envFallbackKeys) {
+        for (const key of envFallbackKeys) {
+            if (!secrets[key] && process.env[key]) {
+                secrets[key] = process.env[key];
+            }
         }
     }
     return secrets;

package/dist/config.test.js

@@ -3,7 +3,7 @@ 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";
+import { config, getFirstRemoteUrl, loadMachineSecrets, parseRepoSlug, resolveRepoSlug, } from "./config.js";
 describe("parseRepoSlug", () => {
     it.each([
         ["https://github.com/redwoodjs/agent-ci.git", "redwoodjs/agent-ci"],
@@ -155,3 +155,79 @@ describe("GITHUB_REPO env var override priority", () => {
         }).toThrow(/Could not detect GitHub repository/);
     });
 });
+// ─── loadMachineSecrets ──────────────────────────────────────────────────────
+describe("loadMachineSecrets", () => {
+    let tmpDir;
+    const savedEnv = {};
+    function saveEnv(...keys) {
+        for (const k of keys) {
+            savedEnv[k] = process.env[k];
+        }
+    }
+    afterEach(() => {
+        if (tmpDir) {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+        for (const [k, v] of Object.entries(savedEnv)) {
+            if (v === undefined) {
+                delete process.env[k];
+            }
+            else {
+                process.env[k] = v;
+            }
+        }
+    });
+    function writeEnvFile(content) {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "secrets-test-"));
+        fs.writeFileSync(path.join(tmpDir, ".env.agent-ci"), content);
+        return tmpDir;
+    }
+    function makeTmpDir() {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "secrets-test-"));
+        return tmpDir;
+    }
+    it("returns empty object when .env.agent-ci does not exist", () => {
+        const dir = makeTmpDir();
+        expect(loadMachineSecrets(dir)).toEqual({});
+    });
+    it("parses KEY=VALUE pairs from file", () => {
+        const dir = writeEnvFile("FOO=bar\nBAZ=qux\n");
+        expect(loadMachineSecrets(dir)).toEqual({ FOO: "bar", BAZ: "qux" });
+    });
+    it("fills missing secrets from process.env when envFallbackKeys provided", () => {
+        const dir = makeTmpDir();
+        saveEnv("TEST_SECRET_ABC");
+        process.env.TEST_SECRET_ABC = "from-env";
+        const secrets = loadMachineSecrets(dir, ["TEST_SECRET_ABC"]);
+        expect(secrets.TEST_SECRET_ABC).toBe("from-env");
+    });
+    it("file values take precedence over process.env", () => {
+        const dir = writeEnvFile("MY_TOKEN=from-file\n");
+        saveEnv("MY_TOKEN");
+        process.env.MY_TOKEN = "from-env";
+        const secrets = loadMachineSecrets(dir, ["MY_TOKEN"]);
+        expect(secrets.MY_TOKEN).toBe("from-file");
+    });
+    it("does not pull from process.env for keys not in envFallbackKeys", () => {
+        const dir = makeTmpDir();
+        saveEnv("UNRELATED_VAR");
+        process.env.UNRELATED_VAR = "should-not-appear";
+        const secrets = loadMachineSecrets(dir, ["OTHER_KEY"]);
+        expect(secrets.UNRELATED_VAR).toBeUndefined();
+        expect(secrets.OTHER_KEY).toBeUndefined();
+    });
+    it("does not pull from process.env when envFallbackKeys is omitted", () => {
+        const dir = makeTmpDir();
+        saveEnv("SOME_SECRET");
+        process.env.SOME_SECRET = "env-value";
+        const secrets = loadMachineSecrets(dir);
+        expect(secrets.SOME_SECRET).toBeUndefined();
+    });
+    it("merges file secrets and env fallbacks", () => {
+        const dir = writeEnvFile("FROM_FILE=file-val\n");
+        saveEnv("FROM_ENV");
+        process.env.FROM_ENV = "env-val";
+        const secrets = loadMachineSecrets(dir, ["FROM_FILE", "FROM_ENV"]);
+        expect(secrets).toEqual({ FROM_FILE: "file-val", FROM_ENV: "env-val" });
+    });
+});

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/image-pull.js

@@ -0,0 +1,42 @@
+/**
+ * Ensures a Docker image is present locally, pulling it if not.
+ *
+ * Docker's createContainer() returns a 404 "No such image" error when the
+ * image is absent — it does not pull automatically. This helper mirrors the
+ * pattern already used by service-containers.ts and must be called before
+ * any createContainer() call.
+ *
+ * Reproduces: https://github.com/redwoodjs/agent-ci/issues/203
+ */
+export async function ensureImagePulled(docker, image) {
+    try {
+        await docker.getImage(image).inspect();
+        return; // already present
+    }
+    catch {
+        // Not found locally — fall through to pull
+    }
+    await new Promise((resolve, reject) => {
+        docker.pull(image, (err, stream) => {
+            if (err) {
+                return reject(wrapPullError(image, err));
+            }
+            docker.modem.followProgress(stream, (err) => {
+                if (err) {
+                    reject(wrapPullError(image, err));
+                }
+                else {
+                    resolve();
+                }
+            });
+        });
+    });
+}
+function wrapPullError(image, cause) {
+    return new Error(`Failed to pull Docker image '${image}': ${cause.message}\n` +
+        "\n" +
+        "  Possible causes:\n" +
+        "    • The image name is misspelled or does not exist in the registry\n" +
+        "    • The image is private — authenticate first: docker login <registry>\n" +
+        "    • No network connection");
+}

package/dist/docker/image-pull.test.js

@@ -0,0 +1,38 @@
+import { describe, it, expect, beforeAll } from "vitest";
+import Docker from "dockerode";
+import { ensureImagePulled } from "./image-pull.js";
+import { resolveDockerSocket } from "./docker-socket.js";
+// Integration test: requires a running Docker daemon and network access.
+// Uses hello-world (~13 KB) to keep pull time minimal.
+const TEST_IMAGE = "hello-world:latest";
+describe("ensureImagePulled", () => {
+    let docker;
+    beforeAll(async () => {
+        const socket = resolveDockerSocket();
+        docker = new Docker({ socketPath: socket.socketPath });
+        await docker.ping();
+    });
+    it("pulls the image when it is not present locally", { timeout: 60000 }, async () => {
+        // Arrange: remove the image so it is definitely absent
+        try {
+            await docker.getImage(TEST_IMAGE).remove({ force: true });
+        }
+        catch {
+            // Already absent — fine
+        }
+        // Act
+        await ensureImagePulled(docker, TEST_IMAGE);
+        // Assert: image must now be inspectable
+        const info = await docker.getImage(TEST_IMAGE).inspect();
+        expect(info.RepoTags).toContain(TEST_IMAGE);
+    });
+    it("rejects with an error when the image does not exist in the registry", { timeout: 30000 }, async () => {
+        await expect(ensureImagePulled(docker, "ghcr.io/redwoodjs/agent-ci-does-not-exist:latest")).rejects.toThrow("Failed to pull Docker image 'ghcr.io/redwoodjs/agent-ci-does-not-exist:latest'");
+    });
+    it("does nothing when the image is already present", async () => {
+        // Arrange: ensure the image is present (previous test or pre-cached)
+        await ensureImagePulled(docker, TEST_IMAGE);
+        // Act: calling again must not throw
+        await expect(ensureImagePulled(docker, TEST_IMAGE)).resolves.toBeUndefined();
+    });
+});

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/output/reporter.js

@@ -10,25 +10,48 @@ function formatDuration(ms) {
     return rem > 0 ? `${m}m ${rem}s` : `${m}m`;
 }
 // ─── Failures-first summary (emitted after all jobs complete) ─────────────────
+function getErrorContent(f) {
+    if (f.failedStepLogPath && fs.existsSync(f.failedStepLogPath)) {
+        return fs.readFileSync(f.failedStepLogPath, "utf-8");
+    }
+    if (f.lastOutputLines && f.lastOutputLines.length > 0) {
+        return f.lastOutputLines.join("\n") + "\n";
+    }
+    return "";
+}
+function formatFailureHeader(f) {
+    if (f.failedStep) {
+        return `  ✗ ${f.workflow} > ${f.taskId} > "${f.failedStep}"`;
+    }
+    return `  ✗ ${f.workflow} > ${f.taskId}`;
+}
 export function printSummary(results, runDir) {
     const failures = results.filter((r) => !r.succeeded);
     const passes = results.filter((r) => r.succeeded);
     const totalMs = results.reduce((sum, r) => sum + r.durationMs, 0);
     if (failures.length > 0) {
         process.stdout.write("\n━━━ FAILURES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n");
+        // Group failures by error content to avoid repeating identical errors
+        const groups = [];
+        const seen = new Map();
         for (const f of failures) {
-            if (f.failedStep) {
-                process.stdout.write(`  ✗ ${f.workflow} > ${f.taskId} > "${f.failedStep}"\n`);
+            const content = getErrorContent(f);
+            const existing = seen.get(content);
+            if (existing) {
+                existing.failures.push(f);
             }
             else {
-                process.stdout.write(`  ✗ ${f.workflow} > ${f.taskId}\n`);
+                const group = { failures: [f], errorContent: content };
+                groups.push(group);
+                seen.set(content, group);
             }
-            if (f.failedStepLogPath && fs.existsSync(f.failedStepLogPath)) {
-                const content = fs.readFileSync(f.failedStepLogPath, "utf-8");
-                process.stdout.write("\n" + content);
+        }
+        for (const group of groups) {
+            for (const f of group.failures) {
+                process.stdout.write(formatFailureHeader(f) + "\n");
             }
-            else if (f.lastOutputLines && f.lastOutputLines.length > 0) {
-                process.stdout.write("\n" + f.lastOutputLines.join("\n") + "\n");
+            if (group.errorContent) {
+                process.stdout.write("\n" + group.errorContent);
             }
             process.stdout.write("\n");
         }

package/dist/output/reporter.test.js

@@ -65,6 +65,50 @@ describe("printSummary", () => {
         ]);
         expect(output).toContain('✗ retry-proof.yml > test > "Run assertion test"');
     });
+    it("deduplicates failures with identical error content", () => {
+        printSummary([
+            makeResult({
+                taskId: "test (1)",
+                failedStep: "[Job startup failed]",
+                lastOutputLines: ["Missing secrets"],
+            }),
+            makeResult({
+                taskId: "test (2)",
+                failedStep: "[Job startup failed]",
+                lastOutputLines: ["Missing secrets"],
+            }),
+            makeResult({
+                taskId: "test (3)",
+                failedStep: "[Job startup failed]",
+                lastOutputLines: ["Missing secrets"],
+            }),
+        ]);
+        // Error content should appear only once
+        const matches = output.match(/Missing secrets/g);
+        expect(matches).toHaveLength(1);
+        // All job headers should still appear
+        expect(output).toContain('test (1) > "[Job startup failed]"');
+        expect(output).toContain('test (2) > "[Job startup failed]"');
+        expect(output).toContain('test (3) > "[Job startup failed]"');
+        // Summary should show correct count
+        expect(output).toContain("3 failed");
+    });
+    it("keeps distinct errors separate", () => {
+        printSummary([
+            makeResult({
+                taskId: "build",
+                failedStep: "Compile",
+                lastOutputLines: ["syntax error"],
+            }),
+            makeResult({
+                taskId: "lint",
+                failedStep: "ESLint",
+                lastOutputLines: ["unused variable"],
+            }),
+        ]);
+        expect(output).toContain("syntax error");
+        expect(output).toContain("unused variable");
+    });
     it("shows pass count in summary for a successful run", () => {
         printSummary([makeResult({ succeeded: true })]);
         expect(output).toContain("✓ 1 passed");

package/dist/output/state-renderer.js

@@ -142,22 +142,22 @@ export function renderRunState(state) {
     const totalJobs = state.workflows.reduce((sum, wf) => sum + wf.jobs.length, 0);
     const singleJobMode = state.workflows.length === 1 && totalJobs === 1;
     const roots = [];
-    let pausedSingleJob;
+    let pausedJob;
     for (const wf of state.workflows) {
         const children = [];
         for (const job of wf.jobs) {
             children.push(...buildJobNodes(job, singleJobMode));
-            // Capture the first paused job for single-job trailing output
-            if (singleJobMode && job.status === "paused" && !pausedSingleJob) {
-                pausedSingleJob = job;
+            // Capture the first paused job for trailing output
+            if (job.status === "paused" && !pausedJob) {
+                pausedJob = job;
             }
         }
         roots.push({ label: path.basename(wf.path), children });
     }
     let output = renderTree(roots);
-    // ── Single-job pause: append last output + retry/abort hints below tree ────
-    if (pausedSingleJob) {
-        const { lastOutputLines, runnerId } = pausedSingleJob;
+    // ── Paused job: append last output + retry/abort hints below tree ──────────
+    if (pausedJob) {
+        const { lastOutputLines, runnerId } = pausedJob;
         if (lastOutputLines && lastOutputLines.length > 0) {
             output += `\n\n  ${DIM}Last output:${RESET}`;
             for (const line of lastOutputLines) {

package/dist/output/state-renderer.test.js

@@ -376,11 +376,54 @@ describe("renderRunState", () => {
                 ],
             });
             const output = renderRunState(state);
-            // Retry hint is a child node (not trailing output like single-job mode)
+            // Retry hint is a child node in the tree
             expect(output).toContain("↻ retry: agent-ci retry --runner agent-ci-5-j2");
-            // No trailing "To retry:" / "To abort:" lines in multi-job mode
-            expect(output).not.toContain("↻ To retry:");
-            expect(output).not.toContain("■ To abort:");
+            // Trailing "To retry:" / "To abort:" lines also shown in multi-job mode
+            expect(output).toContain("↻ To retry:");
+            expect(output).toContain("■ To abort:");
+        });
+        it("shows last output lines for paused job in multi-job mode", () => {
+            const state = makeState({
+                workflows: [
+                    {
+                        id: "ci.yml",
+                        path: "/repo/.github/workflows/ci.yml",
+                        status: "running",
+                        jobs: [
+                            {
+                                id: "build",
+                                runnerId: "agent-ci-5-j1",
+                                status: "completed",
+                                durationMs: 5000,
+                                steps: [],
+                            },
+                            {
+                                id: "test",
+                                runnerId: "agent-ci-5-j2",
+                                status: "paused",
+                                pausedAtStep: "Run tests",
+                                pausedAtMs: "1970-01-01T00:00:05.000Z",
+                                attempt: 1,
+                                lastOutputLines: ["FAIL src/app.test.ts", "  Expected: true", "  Received: false"],
+                                bootDurationMs: 1000,
+                                steps: [
+                                    {
+                                        name: "Run tests",
+                                        index: 1,
+                                        status: "paused",
+                                        startedAt: "1970-01-01T00:00:03.000Z",
+                                    },
+                                ],
+                            },
+                        ],
+                    },
+                ],
+            });
+            const output = renderRunState(state);
+            expect(output).toContain("Last output:");
+            expect(output).toContain("FAIL src/app.test.ts");
+            expect(output).toContain("Expected: true");
+            expect(output).toContain("Received: false");
         });
     });
     describe("multi-workflow (--all mode)", () => {

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/dirty-sha.js

@@ -0,0 +1,64 @@
+import { execSync } from "child_process";
+import path from "path";
+import fs from "fs";
+/**
+ * Compute a SHA that represents the current dirty working-tree state, as if
+ * it were committed.  Uses a temporary index + `git write-tree` /
+ * `git commit-tree` so no refs are moved and real history is untouched.
+ *
+ * Returns `undefined` when the tree is clean (no uncommitted changes).
+ */
+export function computeDirtySha(repoRoot) {
+    try {
+        // Quick check: anything dirty?
+        const status = execSync("git status --porcelain", {
+            cwd: repoRoot,
+            stdio: "pipe",
+        })
+            .toString()
+            .trim();
+        if (!status) {
+            return undefined;
+        }
+        const gitDir = execSync("git rev-parse --git-dir", {
+            cwd: repoRoot,
+            stdio: "pipe",
+        })
+            .toString()
+            .trim();
+        const absoluteGitDir = path.isAbsolute(gitDir) ? gitDir : path.join(repoRoot, gitDir);
+        const tmpIndex = path.join(absoluteGitDir, `index-agent-ci-${Date.now()}`);
+        try {
+            // Seed the temp index from the real one so we start from the current staging area.
+            fs.copyFileSync(path.join(absoluteGitDir, "index"), tmpIndex);
+            const env = { ...process.env, GIT_INDEX_FILE: tmpIndex };
+            // Stage everything (tracked + untracked, respecting .gitignore) into the temp index.
+            execSync("git add -A", { cwd: repoRoot, stdio: "pipe", env });
+            // Write a tree object from the temp index.
+            const tree = execSync("git write-tree", {
+                cwd: repoRoot,
+                stdio: "pipe",
+                env,
+            })
+                .toString()
+                .trim();
+            // Create an ephemeral commit object parented on HEAD — no ref is updated.
+            const sha = execSync(`git commit-tree ${tree} -p HEAD -m "agent-ci: dirty working tree"`, {
+                cwd: repoRoot,
+                stdio: "pipe",
+            })
+                .toString()
+                .trim();
+            return sha;
+        }
+        finally {
+            try {
+                fs.unlinkSync(tmpIndex);
+            }
+            catch { }
+        }
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/runner/dirty-sha.test.js

@@ -0,0 +1,101 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { execSync } from "child_process";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { computeDirtySha } from "./dirty-sha.js";
+describe("computeDirtySha", () => {
+    let repoDir;
+    beforeEach(() => {
+        repoDir = fs.mkdtempSync(path.join(os.tmpdir(), "dirty-sha-test-"));
+        execSync("git init", { cwd: repoDir, stdio: "pipe" });
+        execSync('git config user.name "test"', { cwd: repoDir, stdio: "pipe" });
+        execSync('git config user.email "test@test.com"', { cwd: repoDir, stdio: "pipe" });
+        // Create an initial commit so HEAD exists
+        fs.writeFileSync(path.join(repoDir, "initial.txt"), "initial");
+        execSync("git add -A && git commit -m 'initial'", { cwd: repoDir, stdio: "pipe" });
+    });
+    afterEach(() => {
+        fs.rmSync(repoDir, { recursive: true, force: true });
+    });
+    it("returns undefined for a clean working tree", () => {
+        expect(computeDirtySha(repoDir)).toBeUndefined();
+    });
+    it("returns a SHA when tracked files are modified", () => {
+        fs.writeFileSync(path.join(repoDir, "initial.txt"), "modified");
+        const sha = computeDirtySha(repoDir);
+        expect(sha).toBeDefined();
+        expect(sha).toMatch(/^[0-9a-f]{40}$/);
+    });
+    it("returns a SHA when untracked files are present", () => {
+        fs.writeFileSync(path.join(repoDir, "untracked.txt"), "new file");
+        const sha = computeDirtySha(repoDir);
+        expect(sha).toBeDefined();
+        expect(sha).toMatch(/^[0-9a-f]{40}$/);
+    });
+    it("returns a different SHA for different dirty states", () => {
+        fs.writeFileSync(path.join(repoDir, "a.txt"), "content a");
+        const sha1 = computeDirtySha(repoDir);
+        // Stage and commit a.txt, then modify differently
+        execSync("git add -A && git commit -m 'add a'", { cwd: repoDir, stdio: "pipe" });
+        fs.writeFileSync(path.join(repoDir, "a.txt"), "content b");
+        const sha2 = computeDirtySha(repoDir);
+        expect(sha1).toBeDefined();
+        expect(sha2).toBeDefined();
+        expect(sha1).not.toBe(sha2);
+    });
+    it("does not move HEAD or create refs", () => {
+        const headBefore = execSync("git rev-parse HEAD", { cwd: repoDir, stdio: "pipe" })
+            .toString()
+            .trim();
+        const refsBefore = execSync("git for-each-ref", { cwd: repoDir, stdio: "pipe" })
+            .toString()
+            .trim();
+        fs.writeFileSync(path.join(repoDir, "dirty.txt"), "dirty");
+        computeDirtySha(repoDir);
+        const headAfter = execSync("git rev-parse HEAD", { cwd: repoDir, stdio: "pipe" })
+            .toString()
+            .trim();
+        const refsAfter = execSync("git for-each-ref", { cwd: repoDir, stdio: "pipe" })
+            .toString()
+            .trim();
+        expect(headAfter).toBe(headBefore);
+        expect(refsAfter).toBe(refsBefore);
+    });
+    it("does not modify the real index", () => {
+        // Stage nothing, but have an untracked file
+        fs.writeFileSync(path.join(repoDir, "untracked.txt"), "new");
+        const statusBefore = execSync("git status --porcelain", { cwd: repoDir, stdio: "pipe" })
+            .toString()
+            .trim();
+        computeDirtySha(repoDir);
+        const statusAfter = execSync("git status --porcelain", { cwd: repoDir, stdio: "pipe" })
+            .toString()
+            .trim();
+        expect(statusAfter).toBe(statusBefore);
+    });
+    it("returns a valid commit object parented on HEAD", () => {
+        fs.writeFileSync(path.join(repoDir, "dirty.txt"), "content");
+        const sha = computeDirtySha(repoDir);
+        expect(sha).toBeDefined();
+        // Verify it's a valid commit object
+        const type = execSync(`git cat-file -t ${sha}`, { cwd: repoDir, stdio: "pipe" })
+            .toString()
+            .trim();
+        expect(type).toBe("commit");
+        // Read the parent SHA directly from the commit object (bypasses any git shims
+        // that intercept `git rev-parse HEAD` in CI environments).
+        const commitBody = execSync(`git cat-file -p ${sha}`, {
+            cwd: repoDir,
+            stdio: "pipe",
+        }).toString();
+        const parentMatch = commitBody.match(/^parent ([0-9a-f]{40})$/m);
+        expect(parentMatch).not.toBeNull();
+        // Read HEAD the same way to compare — resolve the ref from .git/HEAD.
+        const headContent = fs.readFileSync(path.join(repoDir, ".git", "HEAD"), "utf-8").trim();
+        const headSha = headContent.startsWith("ref: ")
+            ? fs.readFileSync(path.join(repoDir, ".git", headContent.slice(5)), "utf-8").trim()
+            : headContent;
+        expect(parentMatch[1]).toBe(headSha);
+    });
+});

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,11 +12,12 @@ 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";
 import { buildJobResult, isJobSuccessful } from "./result-builder.js";
+import { ensureImagePulled } from "../docker/image-pull.js";
 import { wrapJobSteps, appendOutputCaptureStep } from "./step-wrapper.js";
 import { syncWorkspaceForRetry } from "./sync.js";
 // ─── Docker setup ─────────────────────────────────────────────────────────────
@@ -184,13 +185,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 +210,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 +250,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 () => {
@@ -300,6 +306,10 @@ export async function executeLocalJob(job, options) {
         const hostRunnerSeedDir = path.resolve(getWorkingDirectory(), "runner");
         const useDirectContainer = !!job.container;
         const containerImage = useDirectContainer ? job.container.image : IMAGE;
+        // Pull the runner image if not cached locally. Required in both modes:
+        // default mode uses it directly as the container image; direct-container
+        // mode uses it to seed the runner binary. Fixes: github.com/redwoodjs/agent-ci/issues/203
+        await ensureImagePulled(getDocker(), IMAGE);
         if (useDirectContainer) {
             await fs.promises.mkdir(hostRunnerSeedDir, { recursive: true });
             const markerFile = path.join(hostRunnerSeedDir, ".seeded");
@@ -449,6 +459,7 @@ export async function executeLocalJob(job, options) {
             warmModulesDir: dirs.warmModulesDir,
             hostRunnerDir,
             useDirectContainer,
+            githubRepo,
             dockerSocketPath: getDockerSocket().socketPath || undefined,
         });
         const containerCmd = buildContainerCmd({
@@ -463,6 +474,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/workflow-parser.js

@@ -663,7 +663,7 @@ export function validateSecrets(filePath, taskName, secrets, secretsFilePath) {
         return;
     }
     throw new Error(`[Agent CI] Missing secrets required by workflow job "${taskName}".\n` +
-        `Add the following to ${secretsFilePath}:\n\n` +
+        `Add the following to ${secretsFilePath} or set them as environment variables:\n\n` +
         missing.map((n) => `${n}=`).join("\n") +
         "\n");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redwoodjs/agent-ci",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "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.1"
+    "dtu-github-actions": "0.9.0"
   },
   "devDependencies": {
     "@types/dockerode": "^3.3.34",