@redwoodjs/agent-ci 0.1.0 → 0.3.0

package/README.md

@@ -12,35 +12,34 @@ Agent CI runs on any machine that can run a container. When a step fails the run
 
 <!-- TODO: Add demo video/screen recording -->
 
-## Installation
-
-```bash
-npm install -g agent-ci
-```
-
-### Prerequisites
+## Prerequisites
 
 - **Docker** — A running Docker provider:
   - **macOS:** [OrbStack](https://orbstack.dev/) (recommended) or Docker Desktop
   - **Linux:** Native Docker Engine
 
-### Remote Docker
-
-Agent CI connects to Docker via the `DOCKER_HOST` environment variable. By default it uses the local socket (`unix:///var/run/docker.sock`), but you can point it at any remote Docker daemon:
+## Installation
 
 ```bash
-# Run containers on a remote machine via SSH
-DOCKER_HOST=ssh://user@remote-server agent-ci run --workflow .github/workflows/ci.yml
+npm install -D @redwoodjs/agent-ci
 ```
 
 ## Usage
 
 ```bash
 # Run a specific workflow
-agent-ci run --workflow .github/workflows/ci.yml
+npx agent-ci run --workflow .github/workflows/ci.yml
 
 # Run all relevant workflows for the current branch
-agent-ci run --all
+npx agent-ci run --all
+```
+
+### Remote Docker
+
+Agent CI connects to Docker via the `DOCKER_HOST` environment variable. By default it uses the local socket (`unix:///var/run/docker.sock`), but you can point it at any remote Docker daemon:
+
+```bash
+DOCKER_HOST=ssh://user@remote-server npx agent-ci run --workflow .github/workflows/ci.yml
 ```
 
 ### `agent-ci run`
@@ -77,3 +76,24 @@ Abort a paused runner and tear down its container.
 ## YAML Compatibility
 
 See [compatibility.md](./compatibility.md) for detailed GitHub Actions workflow syntax support.
+
+## Debugging
+
+Set the `DEBUG` environment variable to enable verbose debug logging. It accepts a comma-separated list of glob patterns matching the namespaces you want to see:
+
+| Value                             | What it shows                 |
+| --------------------------------- | ----------------------------- |
+| `DEBUG=agent-ci:*`                | All debug output              |
+| `DEBUG=agent-ci:cli`              | CLI-level logs only           |
+| `DEBUG=agent-ci:runner`           | Runner/container logs only    |
+| `DEBUG=agent-ci:dtu`              | DTU mock-server logs only     |
+| `DEBUG=agent-ci:boot`             | Boot/startup timing logs only |
+| `DEBUG=agent-ci:cli,agent-ci:dtu` | Multiple namespaces           |
+
+- Output goes to **stderr** so stdout stays clean for piping.
+- If `DEBUG` is unset or empty, all debug loggers become **no-ops** (zero overhead).
+- Pattern matching uses [minimatch](https://github.com/isaacs/minimatch) globs, so `agent-ci:*` matches all four namespaces.
+
+```bash
+DEBUG=agent-ci:* npx agent-ci run
+```

package/dist/cli.js

@@ -6,7 +6,8 @@ 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 { getWorkflowTemplate, parseWorkflowSteps, parseWorkflowServices, parseWorkflowContainer, validateSecrets, parseMatrixDef, expandMatrixCombinations, isWorkflowRelevant, getChangedFiles, } from "./workflow/workflow-parser.js";
+import { getWorkflowTemplate, parseWorkflowSteps, parseWorkflowServices, parseWorkflowContainer, validateSecrets, parseMatrixDef, expandMatrixCombinations, isWorkflowRelevant, getChangedFiles, parseJobOutputDefs, parseJobIf, evaluateJobIf, parseFailFast, } 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";
@@ -497,24 +498,36 @@ async function handleWorkflow(options) {
                 taskId: ej.taskName,
             };
         };
-        const runJob = async (ej) => {
+        const runJob = async (ej, needsContext) => {
             const { taskName, matrixContext } = ej;
             debugCli(`Running: ${path.basename(workflowPath)} | Task: ${taskName}${matrixContext ? ` | Matrix: ${JSON.stringify(Object.fromEntries(Object.entries(matrixContext).filter(([k]) => !k.startsWith("__"))))}` : ""}`);
             const secrets = loadMachineSecrets(repoRoot);
             const secretsFilePath = path.join(repoRoot, ".env.agent-ci");
             validateSecrets(workflowPath, taskName, secrets, secretsFilePath);
-            const steps = await parseWorkflowSteps(workflowPath, taskName, secrets, matrixContext);
+            const steps = await parseWorkflowSteps(workflowPath, taskName, secrets, matrixContext, needsContext);
             const services = await parseWorkflowServices(workflowPath, taskName);
             const container = await parseWorkflowContainer(workflowPath, taskName);
             const job = buildJob(ej);
             job.steps = steps;
             job.services = services;
             job.container = container ?? undefined;
-            return executeLocalJob(job, { pauseOnFailure, store });
+            const result = await executeLocalJob(job, { pauseOnFailure, store });
+            // result.outputs now contains raw step outputs (extracted inside executeLocalJob
+            // before workspace cleanup). Resolve them to job-level outputs using the
+            // output definitions from the workflow YAML.
+            if (result.outputs && Object.keys(result.outputs).length > 0) {
+                const outputDefs = parseJobOutputDefs(workflowPath, taskName);
+                if (Object.keys(outputDefs).length > 0) {
+                    result.outputs = resolveJobOutputs(outputDefs, result.outputs);
+                }
+            }
+            return result;
         };
         pruneOrphanedDockerResources();
         const limiter = createConcurrencyLimiter(maxJobs);
         const allResults = [];
+        // Accumulate job outputs across waves for needs.*.outputs.* resolution
+        const jobOutputs = new Map();
         // ── Dependency-aware wave scheduling ──────────────────────────────────────
         const deps = parseJobDependencies(workflowPath);
         const waves = topoSort(deps);
@@ -525,6 +538,73 @@ async function handleWorkflow(options) {
         if (filteredWaves.length === 0) {
             filteredWaves.push(Array.from(taskNamesInWf));
         }
+        /** Build a needsContext for a job from its dependencies' accumulated outputs */
+        const buildNeedsContext = (jobId) => {
+            const jobDeps = deps.get(jobId);
+            if (!jobDeps || jobDeps.length === 0) {
+                return undefined;
+            }
+            const ctx = {};
+            for (const depId of jobDeps) {
+                ctx[depId] = jobOutputs.get(depId) ?? {};
+            }
+            return ctx;
+        };
+        /** Collect outputs from a completed job result */
+        const collectOutputs = (result, taskName) => {
+            if (result.outputs && Object.keys(result.outputs).length > 0) {
+                jobOutputs.set(taskName, result.outputs);
+            }
+        };
+        // Track job results for if-condition evaluation (success/failure status)
+        const jobResultStatus = new Map();
+        /** Check if a job should be skipped based on its if: condition */
+        const shouldSkipJob = (jobId) => {
+            const ifExpr = parseJobIf(workflowPath, jobId);
+            if (ifExpr === null) {
+                // No if: condition — default behavior is success() (skip if any upstream failed)
+                const jobDeps = deps.get(jobId);
+                if (jobDeps && jobDeps.length > 0) {
+                    const anyFailed = jobDeps.some((d) => jobResultStatus.get(d) === "failure");
+                    if (anyFailed) {
+                        return true;
+                    }
+                }
+                return false;
+            }
+            // Build upstream job results for the evaluator
+            const upstreamResults = {};
+            const jobDeps = deps.get(jobId) ?? [];
+            for (const depId of jobDeps) {
+                upstreamResults[depId] = jobResultStatus.get(depId) ?? "success";
+            }
+            const needsCtx = buildNeedsContext(jobId);
+            return !evaluateJobIf(ifExpr, upstreamResults, needsCtx);
+        };
+        /** Create a synthetic skipped result for a job that was skipped by if: */
+        const skippedResult = (ej) => ({
+            name: `agent-ci-skipped-${ej.taskName}`,
+            workflow: path.basename(workflowPath),
+            taskId: ej.taskName,
+            succeeded: true,
+            durationMs: 0,
+            debugLogPath: "",
+            steps: [],
+        });
+        /** Run a job or skip it based on if: condition */
+        const runOrSkipJob = async (ej) => {
+            if (shouldSkipJob(ej.taskName)) {
+                debugCli(`Skipping ${ej.taskName} (if: condition is false)`);
+                const result = skippedResult(ej);
+                jobResultStatus.set(ej.taskName, "skipped");
+                return result;
+            }
+            const ctx = buildNeedsContext(ej.taskName);
+            const result = await runJob(ej, ctx);
+            jobResultStatus.set(ej.taskName, result.succeeded ? "success" : "failure");
+            collectOutputs(result, ej.taskName);
+            return result;
+        };
         for (let wi = 0; wi < filteredWaves.length; wi++) {
             const waveJobIds = new Set(filteredWaves[wi]);
             const waveJobs = expandedJobs.filter((j) => waveJobIds.has(j.taskName));
@@ -534,9 +614,9 @@ async function handleWorkflow(options) {
             // ── Warm-cache serialization for the first wave ────────────────────────
             if (!warm && wi === 0 && waveJobs.length > 1) {
                 debugCli("Cold cache — running first job to populate warm modules...");
-                const firstResult = await runJob(waveJobs[0]);
+                const firstResult = await runOrSkipJob(waveJobs[0]);
                 allResults.push(firstResult);
-                const results = await Promise.allSettled(waveJobs.slice(1).map((ej) => limiter.run(() => runJob(ej))));
+                const results = await Promise.allSettled(waveJobs.slice(1).map((ej) => limiter.run(() => runOrSkipJob(ej))));
                 for (const r of results) {
                     if (r.status === "fulfilled") {
                         allResults.push(r.value);
@@ -545,17 +625,27 @@ async function handleWorkflow(options) {
                 warm = true;
             }
             else {
-                const results = await Promise.allSettled(waveJobs.map((ej) => limiter.run(() => runJob(ej))));
+                const results = await Promise.allSettled(waveJobs.map((ej) => limiter.run(() => runOrSkipJob(ej))));
                 for (const r of results) {
                     if (r.status === "fulfilled") {
                         allResults.push(r.value);
                     }
                 }
             }
-            // Abort remaining waves if this wave had failures
-            if (allResults.some((r) => !r.succeeded) && wi < filteredWaves.length - 1) {
-                debugCli(`Wave ${wi + 1} had failures — aborting remaining waves for ${path.basename(workflowPath)}`);
-                break;
+            // Check whether to abort remaining waves on failure
+            const waveHadFailures = allResults.some((r) => !r.succeeded);
+            if (waveHadFailures && wi < filteredWaves.length - 1) {
+                // Check fail-fast setting for jobs in this wave
+                const waveFailFastSettings = waveJobs.map((ej) => parseFailFast(workflowPath, ej.taskName));
+                // Abort unless ALL jobs in the wave explicitly set fail-fast: false
+                const shouldAbort = !waveFailFastSettings.every((ff) => ff === false);
+                if (shouldAbort) {
+                    debugCli(`Wave ${wi + 1} had failures — aborting remaining waves for ${path.basename(workflowPath)}`);
+                    break;
+                }
+                else {
+                    debugCli(`Wave ${wi + 1} had failures but fail-fast is disabled — continuing`);
+                }
             }
         }
         return allResults;

package/dist/output/working-directory.js

@@ -2,7 +2,7 @@ import path from "node:path";
 import os from "node:os";
 import fs from "node:fs";
 import { fileURLToPath } from "node:url";
-// Pinned to the monorepo root (project root), not the cli package
+// Pinned to the cli package root
 export const PROJECT_ROOT = path.resolve(fileURLToPath(import.meta.url), "..", "..", "..");
 // When running inside a container with Docker-outside-of-Docker (shared socket),
 // /tmp is NOT visible to the Docker host. Use a project-relative directory

package/dist/runner/local-job.js

@@ -17,7 +17,7 @@ import { prepareWorkspace } from "./workspace.js";
 import { createRunDirectories } from "./directory-setup.js";
 import { buildContainerEnv, buildContainerBinds, buildContainerCmd, resolveDtuHost, resolveDockerApiUrl, } from "../docker/container-config.js";
 import { buildJobResult, sanitizeStepName } from "./result-builder.js";
-import { wrapJobSteps } from "./step-wrapper.js";
+import { wrapJobSteps, appendOutputCaptureStep } from "./step-wrapper.js";
 import { syncWorkspaceForRetry } from "./sync.js";
 // ─── Docker setup ─────────────────────────────────────────────────────────────
 const dockerHost = process.env.DOCKER_HOST || "unix:///var/run/docker.sock";
@@ -169,7 +169,8 @@ export async function executeLocalJob(job, options) {
                 default_branch: job.repository?.default_branch || "main",
             }
             : job.repository;
-        const seededSteps = pauseOnFailure ? wrapJobSteps(job.steps ?? [], true) : job.steps;
+        const wrappedSteps = pauseOnFailure ? wrapJobSteps(job.steps ?? [], true) : job.steps;
+        const seededSteps = appendOutputCaptureStep(wrappedSteps ?? []);
         t0 = Date.now();
         const seedResponse = await fetch(`${dtuUrl}/_dtu/seed`, {
             method: "POST",
@@ -668,6 +669,19 @@ export async function executeLocalJob(job, options) {
         if (fs.existsSync(hostRunnerDir)) {
             fs.rmSync(hostRunnerDir, { recursive: true, force: true });
         }
+        // Read step outputs captured by the DTU server via the runner's outputs API
+        let stepOutputs = {};
+        if (jobSucceeded) {
+            const outputsFile = path.join(logDir, "outputs.json");
+            try {
+                if (fs.existsSync(outputsFile)) {
+                    stepOutputs = JSON.parse(fs.readFileSync(outputsFile, "utf-8"));
+                }
+            }
+            catch {
+                /* best-effort */
+            }
+        }
         if (jobSucceeded && fs.existsSync(dirs.containerWorkDir)) {
             fs.rmSync(dirs.containerWorkDir, { recursive: true, force: true });
         }
@@ -682,6 +696,7 @@ export async function executeLocalJob(job, options) {
             timelinePath,
             logDir,
             debugLogPath,
+            stepOutputs,
         });
     }
     finally {

package/dist/runner/result-builder.js

@@ -83,11 +83,117 @@ export function extractFailureDetails(timelinePath, failedStepName, logDir) {
     }
     return result;
 }
+// ─── Step output extraction ───────────────────────────────────────────────────
+/**
+ * Extract step outputs from the runner's `_runner_file_commands/` directory.
+ *
+ * The GitHub Actions runner writes step outputs to files named `set_output_<uuid>`
+ * in `<workDir>/_runner_file_commands/`. Each file contains key=value pairs,
+ * with multiline values using the heredoc format:
+ *   key<<DELIMITER
+ *   line1
+ *   line2
+ *   DELIMITER
+ *
+ * @param workDir The container's work directory (bind-mounted from host)
+ * @returns Record<string, string> of all output key-value pairs
+ */
+export function extractStepOutputs(workDir) {
+    const outputs = {};
+    // The runner writes to _temp/_runner_file_commands/ under the work dir
+    // $GITHUB_OUTPUT = /home/runner/_work/_temp/_runner_file_commands/set_output_<uuid>
+    const candidates = [
+        path.join(workDir, "_temp", "_runner_file_commands"),
+        path.join(workDir, "_runner_file_commands"),
+    ];
+    for (const fileCommandsDir of candidates) {
+        if (!fs.existsSync(fileCommandsDir)) {
+            continue;
+        }
+        let entries;
+        try {
+            entries = fs.readdirSync(fileCommandsDir).sort(); // Sort for deterministic override order
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.startsWith("set_output_")) {
+                continue;
+            }
+            try {
+                const content = fs.readFileSync(path.join(fileCommandsDir, entry), "utf-8");
+                parseOutputFileContent(content, outputs);
+            }
+            catch {
+                // Best-effort: skip unreadable files
+            }
+        }
+    }
+    return outputs;
+}
+/**
+ * Parse the content of a single set_output file into the outputs record.
+ * Handles both `key=value` and `key<<DELIMITER\nvalue\nDELIMITER` formats.
+ */
+function parseOutputFileContent(content, outputs) {
+    const lines = content.split("\n");
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        // Heredoc format: key<<DELIMITER
+        const heredocMatch = line.match(/^([^=]+)<<(.+)$/);
+        if (heredocMatch) {
+            const key = heredocMatch[1];
+            const delimiter = heredocMatch[2];
+            const valueLines = [];
+            i++;
+            while (i < lines.length && lines[i] !== delimiter) {
+                valueLines.push(lines[i]);
+                i++;
+            }
+            outputs[key] = valueLines.join("\n");
+            i++; // Skip the closing delimiter
+            continue;
+        }
+        // Simple format: key=value
+        const eqIdx = line.indexOf("=");
+        if (eqIdx > 0) {
+            const key = line.slice(0, eqIdx);
+            const value = line.slice(eqIdx + 1);
+            outputs[key] = value;
+        }
+        i++;
+    }
+}
+// ─── Job output resolution ────────────────────────────────────────────────────
+/**
+ * Resolve job output definitions against actual step outputs.
+ *
+ * Job output templates reference `steps.<stepId>.outputs.<name>`. Since the
+ * runner writes all step outputs to `$GITHUB_OUTPUT` files keyed only by
+ * output name (not step ID), we resolve by matching the output name from
+ * the template against the flat step outputs map.
+ *
+ * @param outputDefs  Job output definitions from parseJobOutputDefs
+ * @param stepOutputs Flat step outputs from extractStepOutputs
+ * @returns Resolved job outputs
+ */
+export function resolveJobOutputs(outputDefs, stepOutputs) {
+    const result = {};
+    for (const [outputName, template] of Object.entries(outputDefs)) {
+        // Replace ${{ steps.<id>.outputs.<name> }} with the actual step output value
+        result[outputName] = template.replace(/\$\{\{\s*steps\.[^.]+\.outputs\.([^\s}]+)\s*\}\}/g, (_match, outputKey) => {
+            return stepOutputs[outputKey] ?? "";
+        });
+    }
+    return result;
+}
 /**
  * Build the structured `JobResult` from container exit state and timeline data.
  */
 export function buildJobResult(opts) {
-    const { containerName, job, startTime, jobSucceeded, lastFailedStep, containerExitCode, timelinePath, logDir, debugLogPath, } = opts;
+    const { containerName, job, startTime, jobSucceeded, lastFailedStep, containerExitCode, timelinePath, logDir, debugLogPath, stepOutputs, } = opts;
     const steps = parseTimelineSteps(timelinePath);
     const result = {
         name: containerName,
@@ -115,5 +221,9 @@ export function buildJobResult(opts) {
             result.lastOutputLines = [];
         }
     }
+    // Attach raw step outputs (will be resolved to job outputs by cli.ts)
+    if (stepOutputs && Object.keys(stepOutputs).length > 0) {
+        result.outputs = stepOutputs;
+    }
     return result;
 }

package/dist/runner/result-builder.test.js

@@ -175,3 +175,141 @@ describe("buildJobResult", () => {
         expect(result.lastOutputLines).toContain("compile error");
     });
 });
+// ── extractStepOutputs ────────────────────────────────────────────────────────
+describe("extractStepOutputs", () => {
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "step-outputs-test-"));
+    });
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it("extracts simple key=value outputs from set_output files", async () => {
+        const { extractStepOutputs } = await import("./result-builder.js");
+        // Simulate the runner's file_commands directory structure
+        const fileCommandsDir = path.join(tmpDir, "_runner_file_commands");
+        fs.mkdirSync(fileCommandsDir, { recursive: true });
+        fs.writeFileSync(path.join(fileCommandsDir, "set_output_abc123"), "skip=false\nshard_count=3\n");
+        const outputs = extractStepOutputs(tmpDir);
+        expect(outputs).toEqual({
+            skip: "false",
+            shard_count: "3",
+        });
+    });
+    it("extracts multiline (heredoc) values", async () => {
+        const { extractStepOutputs } = await import("./result-builder.js");
+        const fileCommandsDir = path.join(tmpDir, "_runner_file_commands");
+        fs.mkdirSync(fileCommandsDir, { recursive: true });
+        fs.writeFileSync(path.join(fileCommandsDir, "set_output_def456"), 'matrix<<EOF\n["1","2","3"]\nEOF\n');
+        const outputs = extractStepOutputs(tmpDir);
+        expect(outputs).toEqual({
+            matrix: '["1","2","3"]',
+        });
+    });
+    it("merges outputs from multiple set_output files", async () => {
+        const { extractStepOutputs } = await import("./result-builder.js");
+        const fileCommandsDir = path.join(tmpDir, "_runner_file_commands");
+        fs.mkdirSync(fileCommandsDir, { recursive: true });
+        fs.writeFileSync(path.join(fileCommandsDir, "set_output_aaa"), "key1=val1\n");
+        fs.writeFileSync(path.join(fileCommandsDir, "set_output_bbb"), "key2=val2\n");
+        const outputs = extractStepOutputs(tmpDir);
+        expect(outputs.key1).toBe("val1");
+        expect(outputs.key2).toBe("val2");
+    });
+    it("returns empty object when no _runner_file_commands directory exists", async () => {
+        const { extractStepOutputs } = await import("./result-builder.js");
+        const outputs = extractStepOutputs(tmpDir);
+        expect(outputs).toEqual({});
+    });
+    it("returns empty object when directory has no set_output files", async () => {
+        const { extractStepOutputs } = await import("./result-builder.js");
+        const fileCommandsDir = path.join(tmpDir, "_runner_file_commands");
+        fs.mkdirSync(fileCommandsDir, { recursive: true });
+        fs.writeFileSync(path.join(fileCommandsDir, "add_path_xyz"), "/usr/local/bin\n");
+        const outputs = extractStepOutputs(tmpDir);
+        expect(outputs).toEqual({});
+    });
+    it("later files override earlier ones for the same key", async () => {
+        const { extractStepOutputs } = await import("./result-builder.js");
+        const fileCommandsDir = path.join(tmpDir, "_runner_file_commands");
+        fs.mkdirSync(fileCommandsDir, { recursive: true });
+        fs.writeFileSync(path.join(fileCommandsDir, "set_output_aaa"), "key=first\n");
+        fs.writeFileSync(path.join(fileCommandsDir, "set_output_zzz"), "key=second\n");
+        const outputs = extractStepOutputs(tmpDir);
+        expect(outputs.key).toBe("second");
+    });
+    it("handles multiline heredoc with multiple lines", async () => {
+        const { extractStepOutputs } = await import("./result-builder.js");
+        const fileCommandsDir = path.join(tmpDir, "_runner_file_commands");
+        fs.mkdirSync(fileCommandsDir, { recursive: true });
+        fs.writeFileSync(path.join(fileCommandsDir, "set_output_multi"), "tests<<DELIM\ntest1.ts\ntest2.ts\ntest3.ts\nDELIM\n");
+        const outputs = extractStepOutputs(tmpDir);
+        expect(outputs.tests).toBe("test1.ts\ntest2.ts\ntest3.ts");
+    });
+});
+// ── resolveJobOutputs ─────────────────────────────────────────────────────────
+describe("resolveJobOutputs", () => {
+    it("resolves step output references in job output templates", async () => {
+        const { resolveJobOutputs } = await import("./result-builder.js");
+        const outputDefs = {
+            skip: "${{ steps.check.outputs.skip }}",
+            count: "${{ steps.counter.outputs.shard_count }}",
+        };
+        const stepOutputs = {
+            skip: "false",
+            shard_count: "3",
+        };
+        const resolved = resolveJobOutputs(outputDefs, stepOutputs);
+        expect(resolved).toEqual({
+            skip: "false",
+            count: "3",
+        });
+    });
+    it("returns empty string for unresolved step outputs", async () => {
+        const { resolveJobOutputs } = await import("./result-builder.js");
+        const outputDefs = {
+            missing: "${{ steps.none.outputs.doesnt_exist }}",
+        };
+        const stepOutputs = {};
+        const resolved = resolveJobOutputs(outputDefs, stepOutputs);
+        expect(resolved).toEqual({ missing: "" });
+    });
+    it("passes through literal values unchanged", async () => {
+        const { resolveJobOutputs } = await import("./result-builder.js");
+        const outputDefs = {
+            version: "1.2.3",
+        };
+        const stepOutputs = {};
+        const resolved = resolveJobOutputs(outputDefs, stepOutputs);
+        expect(resolved).toEqual({ version: "1.2.3" });
+    });
+    it("returns empty object when no output definitions", async () => {
+        const { resolveJobOutputs } = await import("./result-builder.js");
+        const resolved = resolveJobOutputs({}, { some: "output" });
+        expect(resolved).toEqual({});
+    });
+    it("handles JSON values in step outputs", async () => {
+        const { resolveJobOutputs } = await import("./result-builder.js");
+        const outputDefs = {
+            matrix: "${{ steps.plan.outputs.matrix }}",
+        };
+        const stepOutputs = {
+            matrix: '{"shard":[1,2,3]}',
+        };
+        const resolved = resolveJobOutputs(outputDefs, stepOutputs);
+        expect(resolved).toEqual({
+            matrix: '{"shard":[1,2,3]}',
+        });
+    });
+    it("handles templates with surrounding text", async () => {
+        const { resolveJobOutputs } = await import("./result-builder.js");
+        const outputDefs = {
+            label: "shard-${{ steps.plan.outputs.index }}",
+        };
+        const stepOutputs = {
+            index: "5",
+        };
+        const resolved = resolveJobOutputs(outputDefs, stepOutputs);
+        expect(resolved).toEqual({ label: "shard-5" });
+    });
+});

package/dist/runner/step-wrapper.js

@@ -80,3 +80,72 @@ export function wrapJobSteps(steps, pauseOnFailure) {
         };
     });
 }
+// ─── Output capture step injection ────────────────────────────────────────────
+//
+// Appends a synthetic step that reads `$GITHUB_OUTPUT` files and echoes their
+// contents to stdout with a `::agent-ci-output::` prefix. The DTU parses these
+// lines and persists them to `outputs.json` so the CLI can resolve cross-job
+// outputs via `needs.*.outputs.*`.
+//
+// This step is necessary because the runner's FinalizeJob step deletes
+// `_temp/_runner_file_commands/` _inside_ the container before it exits,
+// making the files unreachable from the host.
+/**
+ * Build the shell script for the output-capture synthetic step.
+ *
+ * Reads all `set_output_*` files from `GITHUB_OUTPUT`'s directory and
+ * echoes each `key=value` line with the prefix `::agent-ci-output::`.
+ * Multiline values (heredoc format) are flattened into single-line JSON.
+ */
+function outputCaptureScript() {
+    return `# Agent CI: capture step outputs for cross-job passing
+DIR="$(dirname "$GITHUB_OUTPUT")"
+if [ -d "$DIR" ]; then
+  for f in "$DIR"/set_output_*; do
+    [ -f "$f" ] || continue
+    while IFS= read -r line || [ -n "$line" ]; do
+      if echo "$line" | grep -q '<<'; then
+        # Heredoc: key<<DELIMITER ... DELIMITER
+        KEY=$(echo "$line" | cut -d'<' -f1)
+        DELIM=$(echo "$line" | sed 's/^[^<]*<<//')
+        VAL=""
+        while IFS= read -r hline || [ -n "$hline" ]; do
+          [ "$hline" = "$DELIM" ] && break
+          [ -n "$VAL" ] && VAL="$VAL\\\\n$hline" || VAL="$hline"
+        done
+        echo "::agent-ci-output::$KEY=$VAL"
+      else
+        echo "::agent-ci-output::$line"
+      fi
+    done < "$f"
+  done
+fi`;
+}
+/**
+ * Create a synthetic step object for output capture.
+ * Uses `if: always()` semantics by setting `Condition` so it runs even
+ * if prior steps failed.
+ */
+export function createOutputCaptureStep() {
+    return {
+        Name: "__agent_ci_output_capture",
+        DisplayName: "Capture outputs",
+        Reference: { Type: "Script" },
+        Inputs: {
+            script: outputCaptureScript(),
+        },
+        Condition: "always()",
+        Environment: {},
+        ContextName: "__agent_ci_output_capture",
+    };
+}
+/**
+ * Append the output-capture step to a steps array.
+ * Only adds it if there are existing steps and the job has outputs defined.
+ */
+export function appendOutputCaptureStep(steps) {
+    if (!steps || steps.length === 0) {
+        return steps;
+    }
+    return [...steps, createOutputCaptureStep()];
+}

package/dist/workflow/workflow-parser.js

@@ -19,7 +19,7 @@ async function loadWorkflowParser() {
  *  - github.sha → '0000000000000000000000000000000000000000'
  *  - (others) → empty string (safe: no commas injected)
  */
-export function expandExpressions(value, repoPath, secrets, matrixContext) {
+export function expandExpressions(value, repoPath, secrets, matrixContext, needsContext) {
     return value.replace(/\$\{\{([\s\S]*?)\}\}/g, (_match, expr) => {
         const trimmed = expr.trim();
         // hashFiles('glob1', 'glob2', ...)
@@ -62,6 +62,45 @@ export function expandExpressions(value, repoPath, secrets, matrixContext) {
                 return "0000000000000000000000000000000000000000";
             }
         }
+        // fromJSON(expr) — parse JSON from a string (or inner expression)
+        const fromJsonMatch = trimmed.match(/^fromJSON\(([\s\S]+)\)$/);
+        if (fromJsonMatch) {
+            const inner = fromJsonMatch[1].trim();
+            // If the inner arg is a quoted string literal, use it directly
+            let rawValue;
+            if ((inner.startsWith("'") && inner.endsWith("'")) ||
+                (inner.startsWith('"') && inner.endsWith('"'))) {
+                rawValue = inner.slice(1, -1);
+            }
+            else {
+                // Otherwise, treat it as an expression and expand it
+                rawValue = expandExpressions(`\${{ ${inner} }}`, repoPath, secrets, matrixContext, needsContext);
+            }
+            try {
+                const parsed = JSON.parse(rawValue);
+                if (typeof parsed === "string") {
+                    return parsed;
+                }
+                return JSON.stringify(parsed);
+            }
+            catch {
+                return "";
+            }
+        }
+        // toJSON(expr) — serialize a value to JSON
+        const toJsonMatch = trimmed.match(/^toJSON\(([\s\S]+)\)$/);
+        if (toJsonMatch) {
+            const inner = toJsonMatch[1].trim();
+            let rawValue;
+            if ((inner.startsWith("'") && inner.endsWith("'")) ||
+                (inner.startsWith('"') && inner.endsWith('"'))) {
+                rawValue = inner.slice(1, -1);
+            }
+            else {
+                rawValue = expandExpressions(`\${{ ${inner} }}`, repoPath, secrets, matrixContext, needsContext);
+            }
+            return JSON.stringify(rawValue);
+        }
         // format('template {0} {1}', arg0, arg1)
         const formatMatch = trimmed.match(/^format\(([\s\S]+)\)$/);
         if (formatMatch) {
@@ -132,6 +171,20 @@ export function expandExpressions(value, repoPath, secrets, matrixContext) {
         if (trimmed.startsWith("steps.")) {
             return "";
         }
+        if (trimmed.startsWith("needs.") && needsContext) {
+            // needs.<jobId>.outputs.<name> or needs.<jobId>.result
+            const parts = trimmed.split(".");
+            const jobId = parts[1];
+            const jobOutputs = needsContext[jobId];
+            if (parts[2] === "outputs" && parts[3]) {
+                return jobOutputs?.[parts[3]] ?? "";
+            }
+            if (parts[2] === "result") {
+                // If the job is in the needsContext, it completed (default to 'success')
+                return jobOutputs ? (jobOutputs["__result"] ?? "success") : "";
+            }
+            return "";
+        }
         if (trimmed.startsWith("needs.")) {
             return "";
         }
@@ -224,7 +277,7 @@ export async function parseMatrixDef(filePath, jobId) {
     }
     return Object.keys(result).length > 0 ? result : null;
 }
-export async function parseWorkflowSteps(filePath, taskName, secrets, matrixContext) {
+export async function parseWorkflowSteps(filePath, taskName, secrets, matrixContext, needsContext) {
     const template = await getWorkflowTemplate(filePath);
     const rawYaml = parseYaml(fs.readFileSync(filePath, "utf8"));
     // Derive repoPath from filePath (.../repoPath/.github/workflows/foo.yml → repoPath)
@@ -244,10 +297,12 @@ export async function parseWorkflowSteps(filePath, taskName, secrets, matrixCont
     return job.steps
         .map((step, index) => {
         const stepId = step.id || `step-${index + 1}`;
-        let stepName = step.name
-            ? expandExpressions(step.name.toString(), repoPath, secrets, matrixContext)
-            : stepId;
         const rawStep = rawSteps[index] || {};
+        // Prefer raw YAML name to preserve ${{ }} expressions for our own expansion
+        const rawName = rawStep.name != null ? String(rawStep.name) : step.name?.toString();
+        let stepName = rawName
+            ? expandExpressions(rawName, repoPath, secrets, matrixContext, needsContext)
+            : stepId;
         // If a step lacks an explicit name, we map it to standard GitHub Actions defaults
         if (!step.name) {
             if ("run" in step) {
@@ -270,7 +325,7 @@ export async function parseWorkflowSteps(filePath, taskName, secrets, matrixCont
             // string is always the complete literal block scalar.
             const rawScript = rawStep.run != null ? String(rawStep.run) : step.run.toString();
             const inputs = {
-                script: expandExpressions(rawScript, repoPath, secrets, matrixContext),
+                script: expandExpressions(rawScript, repoPath, secrets, matrixContext, needsContext),
             };
             if (rawStep["working-directory"]) {
                 inputs.workingDirectory = rawStep["working-directory"];
@@ -287,7 +342,7 @@ export async function parseWorkflowSteps(filePath, taskName, secrets, matrixCont
                 Env: rawStep.env
                     ? Object.fromEntries(Object.entries(rawStep.env).map(([k, v]) => [
                         k,
-                        expandExpressions(String(v), repoPath, secrets),
+                        expandExpressions(String(v), repoPath, secrets, undefined, needsContext),
                     ]))
                     : undefined,
             };
@@ -322,13 +377,13 @@ export async function parseWorkflowSteps(filePath, taskName, secrets, matrixCont
                     ...(step.with
                         ? Object.fromEntries(Object.entries(step.with).map(([k, v]) => [
                             k,
-                            expandExpressions(String(v), repoPath, secrets, matrixContext),
+                            expandExpressions(String(v), repoPath, secrets, matrixContext, needsContext),
                         ]))
                         : {}),
                     // Merge from raw YAML (overrides parsed values), expanding expressions
                     ...Object.fromEntries(Object.entries(stepWith).map(([k, v]) => [
                         k,
-                        expandExpressions(String(v), repoPath, secrets, matrixContext),
+                        expandExpressions(String(v), repoPath, secrets, matrixContext, needsContext),
                     ])),
                     ...(isCheckout
                         ? {
@@ -338,7 +393,7 @@ export async function parseWorkflowSteps(filePath, taskName, secrets, matrixCont
                             submodules: "false",
                             ...Object.fromEntries(Object.entries(stepWith).map(([k, v]) => [
                                 k,
-                                expandExpressions(String(v), repoPath),
+                                expandExpressions(String(v), repoPath, secrets, undefined, needsContext),
                             ])),
                         }
                         : {}), // Prevent actions/checkout from wiping the rsynced workspace
@@ -346,7 +401,7 @@ export async function parseWorkflowSteps(filePath, taskName, secrets, matrixCont
                 Env: rawStep.env
                     ? Object.fromEntries(Object.entries(rawStep.env).map(([k, v]) => [
                         k,
-                        expandExpressions(String(v), repoPath, secrets, matrixContext),
+                        expandExpressions(String(v), repoPath, secrets, matrixContext, needsContext),
                     ]))
                     : undefined,
             };
@@ -554,3 +609,183 @@ export function validateSecrets(filePath, taskName, secrets, secretsFilePath) {
         missing.map((n) => `${n}=`).join("\n") +
         "\n");
 }
+/**
+ * Parse `jobs.<id>.outputs` definitions from a workflow YAML file.
+ * Returns a Record<outputName, expressionTemplate> (e.g. { skip: "${{ steps.check.outputs.skip }}" }).
+ * Returns {} if the job has no outputs or doesn't exist.
+ */
+export function parseJobOutputDefs(filePath, jobId) {
+    const yaml = parseYaml(fs.readFileSync(filePath, "utf8"));
+    const outputs = yaml?.jobs?.[jobId]?.outputs;
+    if (!outputs || typeof outputs !== "object") {
+        return {};
+    }
+    const result = {};
+    for (const [k, v] of Object.entries(outputs)) {
+        result[k] = String(v);
+    }
+    return result;
+}
+/**
+ * Parse the `if:` condition from a workflow job.
+ * Returns the raw expression string (with `${{ }}` wrapper stripped if present),
+ * or null if the job has no `if:`.
+ */
+export function parseJobIf(filePath, jobId) {
+    const yaml = parseYaml(fs.readFileSync(filePath, "utf8"));
+    const rawIf = yaml?.jobs?.[jobId]?.if;
+    if (rawIf == null) {
+        return null;
+    }
+    let expr = String(rawIf).trim();
+    // Strip ${{ }} wrapper if present
+    const wrapped = expr.match(/^\$\{\{\s*([\s\S]*?)\s*\}\}$/);
+    if (wrapped) {
+        expr = wrapped[1];
+    }
+    return expr;
+}
+/**
+ * Evaluate a job-level `if:` condition.
+ *
+ * @param expr       The expression string (already stripped of `${{ }}`)
+ * @param jobResults Record<jobId, "success" | "failure"> for upstream jobs
+ * @param needsCtx   Optional needs output context (same shape as expandExpressions needsContext)
+ * @returns          Whether the job should run
+ */
+export function evaluateJobIf(expr, jobResults, needsCtx) {
+    const trimmed = expr.trim();
+    // Empty expression defaults to success()
+    if (!trimmed) {
+        return evaluateAtom("success()", jobResults, needsCtx);
+    }
+    // Handle || (split first — lower precedence)
+    if (trimmed.includes("||")) {
+        const parts = splitOnOperator(trimmed, "||");
+        if (parts.length > 1) {
+            return parts.some((p) => evaluateJobIf(p.trim(), jobResults, needsCtx));
+        }
+    }
+    // Handle &&
+    if (trimmed.includes("&&")) {
+        const parts = splitOnOperator(trimmed, "&&");
+        if (parts.length > 1) {
+            return parts.every((p) => evaluateJobIf(p.trim(), jobResults, needsCtx));
+        }
+    }
+    return evaluateAtom(trimmed, jobResults, needsCtx);
+}
+/**
+ * Split an expression on a logical operator, respecting parentheses and quotes.
+ */
+function splitOnOperator(expr, op) {
+    const parts = [];
+    let depth = 0;
+    let inQuote = null;
+    let current = "";
+    for (let i = 0; i < expr.length; i++) {
+        const ch = expr[i];
+        if (inQuote) {
+            current += ch;
+            if (ch === inQuote) {
+                inQuote = null;
+            }
+            continue;
+        }
+        if (ch === "'" || ch === '"') {
+            inQuote = ch;
+            current += ch;
+            continue;
+        }
+        if (ch === "(") {
+            depth++;
+        }
+        if (ch === ")") {
+            depth--;
+        }
+        if (depth === 0 && expr.slice(i, i + op.length) === op) {
+            parts.push(current);
+            current = "";
+            i += op.length - 1;
+            continue;
+        }
+        current += ch;
+    }
+    parts.push(current);
+    return parts;
+}
+/**
+ * Evaluate a single atomic condition (no && or ||).
+ */
+function evaluateAtom(expr, jobResults, needsCtx) {
+    const trimmed = expr.trim();
+    // Status check functions
+    if (trimmed === "always()") {
+        return true;
+    }
+    if (trimmed === "cancelled()") {
+        return false;
+    }
+    if (trimmed === "success()") {
+        return Object.values(jobResults).every((r) => r === "success");
+    }
+    if (trimmed === "failure()") {
+        return Object.values(jobResults).some((r) => r === "failure");
+    }
+    // != comparison
+    const neqMatch = trimmed.match(/^(.+?)\s*!=\s*(.+)$/);
+    if (neqMatch) {
+        const left = resolveValue(neqMatch[1].trim(), needsCtx);
+        const right = resolveValue(neqMatch[2].trim(), needsCtx);
+        return left !== right;
+    }
+    // == comparison
+    const eqMatch = trimmed.match(/^(.+?)\s*==\s*(.+)$/);
+    if (eqMatch) {
+        const left = resolveValue(eqMatch[1].trim(), needsCtx);
+        const right = resolveValue(eqMatch[2].trim(), needsCtx);
+        return left === right;
+    }
+    // Bare truthy value (e.g. needs.setup.outputs.run_tests)
+    const val = resolveValue(trimmed, needsCtx);
+    return val !== "" && val !== "false" && val !== "0";
+}
+/**
+ * Resolve a value reference in a condition expression.
+ */
+function resolveValue(raw, needsCtx) {
+    const trimmed = raw.trim();
+    // Quoted string literal
+    if ((trimmed.startsWith("'") && trimmed.endsWith("'")) ||
+        (trimmed.startsWith('"') && trimmed.endsWith('"'))) {
+        return trimmed.slice(1, -1);
+    }
+    // needs.<jobId>.outputs.<name>
+    if (trimmed.startsWith("needs.") && needsCtx) {
+        const parts = trimmed.split(".");
+        const jobId = parts[1];
+        const jobOutputs = needsCtx[jobId];
+        if (parts[2] === "outputs" && parts[3]) {
+            return jobOutputs?.[parts[3]] ?? "";
+        }
+        if (parts[2] === "result") {
+            return jobOutputs ? (jobOutputs["__result"] ?? "success") : "";
+        }
+    }
+    return trimmed;
+}
+/**
+ * Parse `strategy.fail-fast` for a job.
+ * Returns true/false if explicitly set, undefined if not specified.
+ */
+export function parseFailFast(filePath, jobId) {
+    const yaml = parseYaml(fs.readFileSync(filePath, "utf8"));
+    const strategy = yaml?.jobs?.[jobId]?.strategy;
+    if (!strategy || typeof strategy !== "object") {
+        return undefined;
+    }
+    if ("fail-fast" in strategy) {
+        return Boolean(strategy["fail-fast"]);
+    }
+    return undefined;
+}

package/dist/workflow/workflow-parser.test.js

@@ -640,3 +640,343 @@ describe("isWorkflowRelevant", () => {
         expect(isWorkflowRelevant(template, "feature", ["cli/src/cli.ts"])).toBe(true);
     });
 });
+// ─── fromJSON / toJSON ────────────────────────────────────────────────────────
+describe("expandExpressions — fromJSON", () => {
+    it("fromJSON parses a JSON array string and returns it", () => {
+        expect(expandExpressions('${{ fromJSON(\'["a","b","c"]\') }}')).toBe('["a","b","c"]');
+    });
+    it("fromJSON parses a JSON string value and unwraps it", () => {
+        expect(expandExpressions("${{ fromJSON('\"hello\"') }}")).toBe("hello");
+    });
+    it("fromJSON parses a JSON number and returns it as string", () => {
+        expect(expandExpressions("${{ fromJSON('42') }}")).toBe("42");
+    });
+    it("fromJSON parses a JSON boolean", () => {
+        expect(expandExpressions("${{ fromJSON('true') }}")).toBe("true");
+        expect(expandExpressions("${{ fromJSON('false') }}")).toBe("false");
+    });
+    it("fromJSON parses a JSON object string", () => {
+        const result = expandExpressions('${{ fromJSON(\'{"key":"val"}\') }}');
+        expect(JSON.parse(result)).toEqual({ key: "val" });
+    });
+    it("fromJSON returns empty string for invalid JSON", () => {
+        expect(expandExpressions("${{ fromJSON('not valid json') }}")).toBe("");
+    });
+    it("fromJSON with a nested expression resolves the inner expr first", () => {
+        // Simulates fromJSON(needs.setup.outputs.matrix) — the inner expr resolves first
+        const needsCtx = { setup: { matrix: '["x","y"]' } };
+        expect(expandExpressions("${{ fromJSON(needs.setup.outputs.matrix) }}", undefined, undefined, undefined, needsCtx)).toBe('["x","y"]');
+    });
+});
+describe("expandExpressions — toJSON", () => {
+    it("toJSON wraps a string value in quotes", () => {
+        expect(expandExpressions("${{ toJSON('hello') }}")).toBe('"hello"');
+    });
+});
+// ─── Cross-job outputs: needs context ─────────────────────────────────────────
+import { parseJobOutputDefs } from "./workflow-parser.js";
+describe("parseJobOutputDefs", () => {
+    let tmpDir;
+    afterEach(() => {
+        if (tmpDir) {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+    });
+    function writeWorkflow(content) {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "oa-outputs-test-"));
+        const filePath = path.join(tmpDir, "workflow.yml");
+        fs.writeFileSync(filePath, content);
+        return filePath;
+    }
+    it("parses job output definitions from YAML", () => {
+        const filePath = writeWorkflow(`
+name: Test Outputs
+on: [push]
+jobs:
+  setup:
+    runs-on: ubuntu-latest
+    outputs:
+      skip: \${{ steps.check.outputs.skip }}
+      shard_count: \${{ steps.count.outputs.shard_count }}
+    steps:
+      - run: echo ok
+`);
+        const defs = parseJobOutputDefs(filePath, "setup");
+        expect(defs).toEqual({
+            skip: "${{ steps.check.outputs.skip }}",
+            shard_count: "${{ steps.count.outputs.shard_count }}",
+        });
+    });
+    it("returns empty object when job has no outputs", () => {
+        const filePath = writeWorkflow(`
+name: No Outputs
+on: [push]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo ok
+`);
+        const defs = parseJobOutputDefs(filePath, "build");
+        expect(defs).toEqual({});
+    });
+    it("returns empty object for nonexistent job", () => {
+        const filePath = writeWorkflow(`
+name: Test
+on: [push]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo ok
+`);
+        const defs = parseJobOutputDefs(filePath, "nonexistent");
+        expect(defs).toEqual({});
+    });
+});
+describe("expandExpressions with needsContext", () => {
+    it("resolves needs.build.outputs.sha to the provided value", () => {
+        const needsCtx = { build: { sha: "abc123" } };
+        expect(expandExpressions("sha=${{ needs.build.outputs.sha }}", undefined, undefined, undefined, needsCtx)).toBe("sha=abc123");
+    });
+    it("resolves needs.setup.outputs.skip to 'false'", () => {
+        const needsCtx = { setup: { skip: "false" } };
+        expect(expandExpressions("${{ needs.setup.outputs.skip }}", undefined, undefined, undefined, needsCtx)).toBe("false");
+    });
+    it("returns empty string for unknown needs output", () => {
+        const needsCtx = { build: { sha: "abc123" } };
+        expect(expandExpressions("${{ needs.build.outputs.unknown }}", undefined, undefined, undefined, needsCtx)).toBe("");
+    });
+    it("returns empty string for unknown needs job", () => {
+        const needsCtx = { build: { sha: "abc123" } };
+        expect(expandExpressions("${{ needs.other.outputs.sha }}", undefined, undefined, undefined, needsCtx)).toBe("");
+    });
+    it("resolves needs.build.result to success when not explicitly set", () => {
+        const needsCtx = { build: {} };
+        // needs.build.result should default to 'success' if the job succeeded
+        expect(expandExpressions("${{ needs.build.result }}", undefined, undefined, undefined, needsCtx)).toBe("success");
+    });
+});
+// ─── Job-level if conditions ──────────────────────────────────────────────────
+import { evaluateJobIf, parseJobIf } from "./workflow-parser.js";
+describe("parseJobIf", () => {
+    let tmpDir;
+    afterEach(() => {
+        if (tmpDir) {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+    });
+    function writeWorkflow(content) {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "oa-job-if-test-"));
+        const filePath = path.join(tmpDir, "workflow.yml");
+        fs.writeFileSync(filePath, content);
+        return filePath;
+    }
+    it("returns the if expression when present", () => {
+        const filePath = writeWorkflow(`
+name: If Test
+on: [push]
+jobs:
+  test:
+    if: needs.setup.outputs.skip == 'false'
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo ok
+`);
+        expect(parseJobIf(filePath, "test")).toBe("needs.setup.outputs.skip == 'false'");
+    });
+    it("returns null when job has no if", () => {
+        const filePath = writeWorkflow(`
+name: No If
+on: [push]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo ok
+`);
+        expect(parseJobIf(filePath, "build")).toBeNull();
+    });
+    it("strips ${{ }} wrapper if present", () => {
+        const filePath = writeWorkflow(`
+name: If Wrapped
+on: [push]
+jobs:
+  check:
+    if: \${{ always() }}
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo ok
+`);
+        expect(parseJobIf(filePath, "check")).toBe("always()");
+    });
+});
+describe("evaluateJobIf", () => {
+    it("always() returns true", () => {
+        expect(evaluateJobIf("always()", {})).toBe(true);
+    });
+    it("success() returns true when all upstream jobs succeeded", () => {
+        expect(evaluateJobIf("success()", { build: "success", lint: "success" })).toBe(true);
+    });
+    it("success() returns false when any upstream job failed", () => {
+        expect(evaluateJobIf("success()", { build: "success", lint: "failure" })).toBe(false);
+    });
+    it("failure() returns true when any upstream job failed", () => {
+        expect(evaluateJobIf("failure()", { build: "success", lint: "failure" })).toBe(true);
+    });
+    it("failure() returns false when all upstream succeeded", () => {
+        expect(evaluateJobIf("failure()", { build: "success" })).toBe(false);
+    });
+    it("cancelled() returns false (locally, nothing is ever cancelled)", () => {
+        expect(evaluateJobIf("cancelled()", {})).toBe(false);
+    });
+    it("evaluates string equality with needs outputs", () => {
+        const needsCtx = { setup: { run_tests: "true" } };
+        expect(evaluateJobIf("needs.setup.outputs.run_tests == 'true'", {}, needsCtx)).toBe(true);
+    });
+    it("evaluates string inequality with needs outputs", () => {
+        const needsCtx = { setup: { run_tests: "false" } };
+        expect(evaluateJobIf("needs.setup.outputs.run_tests == 'true'", {}, needsCtx)).toBe(false);
+    });
+    it("evaluates != operator", () => {
+        const needsCtx = { setup: { skip: "false" } };
+        expect(evaluateJobIf("needs.setup.outputs.skip != 'true'", {}, needsCtx)).toBe(true);
+    });
+    it("evaluates compound condition with &&", () => {
+        const needsCtx = { setup: { skip: "false", run_tests: "true" } };
+        expect(evaluateJobIf("needs.setup.outputs.skip == 'false' && needs.setup.outputs.run_tests == 'true'", {}, needsCtx)).toBe(true);
+    });
+    it("evaluates compound condition with || where first is false", () => {
+        expect(evaluateJobIf("failure() || always()", { build: "success" })).toBe(true);
+    });
+    it("defaults to success() when expression is empty", () => {
+        expect(evaluateJobIf("", { build: "success" })).toBe(true);
+        expect(evaluateJobIf("", { build: "failure" })).toBe(false);
+    });
+});
+// ─── strategy.fail-fast ──────────────────────────────────────────────────────
+import { parseFailFast } from "./workflow-parser.js";
+describe("parseFailFast", () => {
+    let tmpDir;
+    afterEach(() => {
+        if (tmpDir) {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+    });
+    function writeWorkflow(content) {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "oa-failfast-test-"));
+        const filePath = path.join(tmpDir, "workflow.yml");
+        fs.writeFileSync(filePath, content);
+        return filePath;
+    }
+    it("returns false when strategy.fail-fast is explicitly false", () => {
+        const filePath = writeWorkflow(`
+name: Fail Fast False
+on: [push]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [1, 2, 3]
+    steps:
+      - run: echo ok
+`);
+        expect(parseFailFast(filePath, "test")).toBe(false);
+    });
+    it("returns true when strategy.fail-fast is explicitly true", () => {
+        const filePath = writeWorkflow(`
+name: Fail Fast True
+on: [push]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: true
+      matrix:
+        shard: [1, 2]
+    steps:
+      - run: echo ok
+`);
+        expect(parseFailFast(filePath, "test")).toBe(true);
+    });
+    it("returns undefined when strategy has no fail-fast key", () => {
+        const filePath = writeWorkflow(`
+name: No Fail Fast
+on: [push]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        shard: [1, 2]
+    steps:
+      - run: echo ok
+`);
+        expect(parseFailFast(filePath, "test")).toBeUndefined();
+    });
+    it("returns undefined when job has no strategy", () => {
+        const filePath = writeWorkflow(`
+name: No Strategy
+on: [push]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo ok
+`);
+        expect(parseFailFast(filePath, "build")).toBeUndefined();
+    });
+});
+// ─── parseWorkflowSteps with needsContext ─────────────────────────────────────
+import { parseWorkflowSteps } from "./workflow-parser.js";
+describe("parseWorkflowSteps with needsContext", () => {
+    let tmpDir;
+    afterEach(() => {
+        if (tmpDir) {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+    });
+    function writeWorkflowTree(content) {
+        // Create a minimal repo structure: repoRoot/.github/workflows/test.yml
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "oa-steps-needs-"));
+        const workflowDir = path.join(tmpDir, ".github", "workflows");
+        fs.mkdirSync(workflowDir, { recursive: true });
+        const filePath = path.join(workflowDir, "test.yml");
+        fs.writeFileSync(filePath, content);
+        return filePath;
+    }
+    it("resolves needs.*.outputs.* in step scripts when needsContext is provided", async () => {
+        const filePath = writeWorkflowTree(`
+name: Needs Test
+on: [push]
+jobs:
+  test:
+    needs: [setup]
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo \${{ needs.setup.outputs.skip }}
+`);
+        const needsCtx = { setup: { skip: "false" } };
+        const steps = await parseWorkflowSteps(filePath, "test", undefined, undefined, needsCtx);
+        // The step script should have "false" substituted in
+        expect(steps[0].Inputs.script).toBe("echo false");
+    });
+    it("resolves needs context in step names", async () => {
+        const filePath = writeWorkflowTree(`
+name: Needs Name Test
+on: [push]
+jobs:
+  test:
+    needs: [setup]
+    runs-on: ubuntu-latest
+    steps:
+      - name: "Shard \${{ needs.setup.outputs.index }}"
+        run: echo hello
+`);
+        const needsCtx = { setup: { index: "3" } };
+        const steps = await parseWorkflowSteps(filePath, "test", undefined, undefined, needsCtx);
+        expect(steps[0].Name).toBe("Shard 3");
+    });
+});

package/package.json

@@ -1,10 +1,15 @@
 {
   "name": "@redwoodjs/agent-ci",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Local GitHub Actions runner",
   "keywords": [],
   "license": "FSL-1.1-MIT",
   "author": "",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/redwoodjs/agent-ci.git",
+    "directory": "packages/cli"
+  },
   "bin": {
     "agent-ci": "./dist/cli.js"
   },
@@ -22,7 +27,7 @@
     "log-update": "^7.2.0",
     "minimatch": "^10.2.1",
     "yaml": "^2.8.2",
-    "dtu-github-actions": "0.1.0"
+    "dtu-github-actions": "0.3.0"
   },
   "devDependencies": {
     "@types/dockerode": "^3.3.34",