@redwoodjs/agent-ci 0.1.0

package/dist/runner/metadata.js

@@ -0,0 +1,90 @@
+import path from "path";
+import fs from "fs";
+// ─── Repo root detection ──────────────────────────────────────────────────────
+/**
+ * Walk up from `startPath` looking for a `.git` directory.
+ * Returns the repo root, or `undefined` if none found.
+ */
+export function findRepoRoot(startPath) {
+    let dir = path.dirname(startPath);
+    while (dir !== "/" && !fs.existsSync(path.join(dir, ".git"))) {
+        dir = path.dirname(dir);
+    }
+    return dir !== "/" ? dir : undefined;
+}
+// ─── Workflow run ID derivation ───────────────────────────────────────────────
+/**
+ * Derive workflowRunId (group key) by stripping job/matrix/retry suffixes.
+ * e.g. agent-ci-redwoodjssdk-14-j1-m2-r2 → agent-ci-redwoodjssdk-14
+ */
+export function deriveWorkflowRunId(containerName) {
+    return containerName.replace(/(-j\d+)?(-m\d+)?(-r\d+)?$/, "");
+}
+/**
+ * Write (or merge into) `metadata.json` in the log directory.
+ *
+ * Preserves orchestrator-written fields like matrixContext, warmCache, etc.
+ * while adding/updating fields derived from the job and container name.
+ */
+export function writeJobMetadata(opts) {
+    const { logDir, containerName, job } = opts;
+    if (!job.workflowPath) {
+        return;
+    }
+    const metadataPath = path.join(logDir, "metadata.json");
+    // Derive repoPath from the workflow file (walk up to find .git)
+    const repoPath = findRepoRoot(job.workflowPath) ?? "";
+    // If the orchestrator (or retryRun) already wrote a metadata.json with the
+    // correct workflowRunId, honour it. This is critical for retries of multi-job
+    // runs (e.g. agent-ci-runner-125-001-001) where a naive regex would strip only a
+    // single suffix and produce the wrong group key.
+    let workflowRunId;
+    let attempt;
+    // Preserve the jobName written by the orchestrator (e.g. "Shard (1/3)") so
+    // human-readable labels aren't overwritten with the raw taskId on process start.
+    let existingJobName = null;
+    if (fs.existsSync(metadataPath)) {
+        try {
+            const existing = JSON.parse(fs.readFileSync(metadataPath, "utf-8"));
+            workflowRunId = existing.workflowRunId;
+            attempt = existing.attempt;
+            if (existing.jobName !== undefined) {
+                existingJobName = existing.jobName;
+            }
+        }
+        catch {
+            // Fall through to derivation
+        }
+    }
+    if (!workflowRunId) {
+        workflowRunId = deriveWorkflowRunId(containerName);
+    }
+    // Build our fields; we'll merge them ON TOP of whatever the orchestrator wrote
+    // so that matrixContext, warmCache, repoPath, etc. are preserved.
+    const freshFields = {
+        workflowPath: job.workflowPath,
+        workflowName: path.basename(job.workflowPath, path.extname(job.workflowPath)),
+        // Prefer the orchestrator-written label; fall back to raw taskId
+        jobName: existingJobName !== null ? existingJobName : (job.taskId ?? null),
+        workflowRunId,
+        commitId: job.headSha || "WORKING_TREE",
+        date: Date.now(),
+        taskId: job.taskId,
+        attempt: attempt ?? 1,
+    };
+    // Only overwrite repoPath if we actually found a .git root; otherwise keep
+    // the orchestrator's value (which is always correct for temp-dir tests too).
+    if (repoPath) {
+        freshFields.repoPath = repoPath;
+    }
+    // Read back existing metadata to preserve orchestrator-written fields
+    // like matrixContext, warmCache, etc.
+    let existingMeta = {};
+    if (fs.existsSync(metadataPath)) {
+        try {
+            existingMeta = JSON.parse(fs.readFileSync(metadataPath, "utf-8"));
+        }
+        catch { }
+    }
+    fs.writeFileSync(metadataPath, JSON.stringify({ ...existingMeta, ...freshFields }, null, 2), "utf-8");
+}

package/dist/runner/metadata.test.js

@@ -0,0 +1,127 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+// ── findRepoRoot ──────────────────────────────────────────────────────────────
+describe("findRepoRoot", () => {
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "meta-root-test-"));
+    });
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it("finds the .git root from a deeply nested path", async () => {
+        const { findRepoRoot } = await import("./metadata.js");
+        // Create .git at root level
+        fs.mkdirSync(path.join(tmpDir, ".git"));
+        // Create a deeply nested file
+        const nested = path.join(tmpDir, "a", "b", "c", "file.txt");
+        fs.mkdirSync(path.dirname(nested), { recursive: true });
+        fs.writeFileSync(nested, "test");
+        expect(findRepoRoot(nested)).toBe(tmpDir);
+    });
+    it("returns undefined when no .git exists", async () => {
+        const { findRepoRoot } = await import("./metadata.js");
+        const file = path.join(tmpDir, "file.txt");
+        fs.writeFileSync(file, "test");
+        expect(findRepoRoot(file)).toBeUndefined();
+    });
+});
+// ── deriveWorkflowRunId ───────────────────────────────────────────────────────
+describe("deriveWorkflowRunId", () => {
+    it("strips job/matrix/retry suffixes", async () => {
+        const { deriveWorkflowRunId } = await import("./metadata.js");
+        expect(deriveWorkflowRunId("agent-ci-redwoodjssdk-14-j1-m2-r2")).toBe("agent-ci-redwoodjssdk-14");
+        expect(deriveWorkflowRunId("agent-ci-redwoodjssdk-14-j1")).toBe("agent-ci-redwoodjssdk-14");
+        expect(deriveWorkflowRunId("agent-ci-redwoodjssdk-14")).toBe("agent-ci-redwoodjssdk-14");
+    });
+    it("handles names without suffixes", async () => {
+        const { deriveWorkflowRunId } = await import("./metadata.js");
+        expect(deriveWorkflowRunId("simple-runner")).toBe("simple-runner");
+    });
+});
+// ── writeJobMetadata ──────────────────────────────────────────────────────────
+describe("writeJobMetadata", () => {
+    let tmpDir;
+    let repoDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "meta-write-test-"));
+        // Create a fake repo root so findRepoRoot works
+        repoDir = path.join(tmpDir, "repo");
+        fs.mkdirSync(path.join(repoDir, ".git"), { recursive: true });
+        fs.mkdirSync(path.join(repoDir, ".github", "workflows"), { recursive: true });
+    });
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it("writes metadata.json with expected fields", async () => {
+        const { writeJobMetadata } = await import("./metadata.js");
+        const logDir = path.join(tmpDir, "logs");
+        fs.mkdirSync(logDir, { recursive: true });
+        const workflowPath = path.join(repoDir, ".github", "workflows", "ci.yml");
+        fs.writeFileSync(workflowPath, "name: CI");
+        writeJobMetadata({
+            logDir,
+            containerName: "agent-ci-test-1",
+            job: {
+                deliveryId: "d1",
+                eventType: "push",
+                login: "test",
+                workflowPath,
+                taskId: "build",
+                headSha: "abc123",
+            },
+        });
+        const meta = JSON.parse(fs.readFileSync(path.join(logDir, "metadata.json"), "utf-8"));
+        expect(meta.workflowPath).toBe(workflowPath);
+        expect(meta.workflowName).toBe("ci");
+        expect(meta.workflowRunId).toBe("agent-ci-test-1");
+        expect(meta.commitId).toBe("abc123");
+        expect(meta.taskId).toBe("build");
+        expect(meta.attempt).toBe(1);
+        expect(meta.repoPath).toBe(repoDir);
+    });
+    it("preserves orchestrator-written fields on merge", async () => {
+        const { writeJobMetadata } = await import("./metadata.js");
+        const logDir = path.join(tmpDir, "logs");
+        fs.mkdirSync(logDir, { recursive: true });
+        const workflowPath = path.join(repoDir, ".github", "workflows", "ci.yml");
+        fs.writeFileSync(workflowPath, "name: CI");
+        // Pre-write orchestrator metadata
+        fs.writeFileSync(path.join(logDir, "metadata.json"), JSON.stringify({
+            workflowRunId: "custom-run-id",
+            matrixContext: { shard: 1 },
+            jobName: "Shard (1/3)",
+            attempt: 2,
+        }));
+        writeJobMetadata({
+            logDir,
+            containerName: "agent-ci-test-1-j1-m1",
+            job: {
+                deliveryId: "d1",
+                eventType: "push",
+                login: "test",
+                workflowPath,
+                taskId: "build",
+            },
+        });
+        const meta = JSON.parse(fs.readFileSync(path.join(logDir, "metadata.json"), "utf-8"));
+        // Orchestrator fields preserved
+        expect(meta.workflowRunId).toBe("custom-run-id");
+        expect(meta.matrixContext).toEqual({ shard: 1 });
+        expect(meta.jobName).toBe("Shard (1/3)");
+        expect(meta.attempt).toBe(2);
+    });
+    it("does nothing when workflowPath is not set", async () => {
+        const { writeJobMetadata } = await import("./metadata.js");
+        const logDir = path.join(tmpDir, "logs");
+        fs.mkdirSync(logDir, { recursive: true });
+        writeJobMetadata({
+            logDir,
+            containerName: "test",
+            job: { deliveryId: "d1", eventType: "push", login: "test" },
+        });
+        expect(fs.existsSync(path.join(logDir, "metadata.json"))).toBe(false);
+    });
+});

package/dist/runner/result-builder.js

@@ -0,0 +1,119 @@
+import path from "path";
+import fs from "fs";
+import { tailLogFile } from "../output/reporter.js";
+// ─── Timeline parsing ─────────────────────────────────────────────────────────
+/**
+ * Read `timeline.json` and map task records into `StepResult[]`.
+ */
+export function parseTimelineSteps(timelinePath) {
+    try {
+        if (!fs.existsSync(timelinePath)) {
+            return [];
+        }
+        const records = JSON.parse(fs.readFileSync(timelinePath, "utf-8"));
+        return records
+            .filter((r) => r.type === "Task" && r.name)
+            .map((r) => ({
+            name: r.name,
+            status: r.result === "Succeeded" || r.result === "succeeded"
+                ? "passed"
+                : r.result === "Failed" || r.result === "failed"
+                    ? "failed"
+                    : r.result === "Skipped" || r.result === "skipped"
+                        ? "skipped"
+                        : r.state === "completed"
+                            ? "passed"
+                            : "skipped",
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+// ─── Step name sanitization ───────────────────────────────────────────────────
+/**
+ * Reproduce the DTU sanitization logic for step log filenames.
+ */
+export function sanitizeStepName(name) {
+    return name
+        .replace(/[^a-zA-Z0-9_.-]/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "")
+        .substring(0, 80);
+}
+/**
+ * Given a failed step name and the timeline, extract:
+ *  - The actual exit code (from the issues array)
+ *  - The path to the step's log file
+ *  - The last N lines of that log
+ */
+export function extractFailureDetails(timelinePath, failedStepName, logDir) {
+    const result = {};
+    try {
+        const timeline = JSON.parse(fs.readFileSync(timelinePath, "utf-8"));
+        const failedRecord = timeline.find((r) => r.name === failedStepName && r.type === "Task");
+        if (!failedRecord) {
+            return result;
+        }
+        // Attempt to parse the actual step exit code from the issues array
+        const issueMsg = failedRecord.issues?.find((i) => i.type === "error")?.message;
+        if (issueMsg) {
+            const m = issueMsg.match(/exit code (\d+)/i);
+            if (m) {
+                result.exitCode = parseInt(m[1], 10);
+            }
+        }
+        const stepsDir = path.join(logDir, "steps");
+        const sanitized = sanitizeStepName(failedStepName);
+        // Try sanitized name first, then record.id (feed handler), then log.id (POST/PUT handlers)
+        for (const id of [sanitized, failedRecord.id, failedRecord.log?.id]) {
+            if (!id) {
+                continue;
+            }
+            const stepLogPath = path.join(stepsDir, `${id}.log`);
+            if (fs.existsSync(stepLogPath)) {
+                result.stepLogPath = stepLogPath;
+                result.tailLines = tailLogFile(stepLogPath);
+                break;
+            }
+        }
+    }
+    catch {
+        /* best-effort */
+    }
+    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 steps = parseTimelineSteps(timelinePath);
+    const result = {
+        name: containerName,
+        workflow: job.workflowPath ? path.basename(job.workflowPath) : "unknown",
+        taskId: job.taskId ?? "unknown",
+        succeeded: jobSucceeded,
+        durationMs: Date.now() - startTime,
+        debugLogPath,
+        steps,
+    };
+    if (!jobSucceeded) {
+        result.failedStep = lastFailedStep ?? undefined;
+        // The container exits with 0 if it successfully reported the job failure,
+        // so only use the container exit code if it actually indicates a crash (non-zero).
+        result.failedExitCode = containerExitCode !== 0 ? containerExitCode : undefined;
+        if (lastFailedStep) {
+            const failure = extractFailureDetails(timelinePath, lastFailedStep, logDir);
+            if (failure.exitCode !== undefined) {
+                result.failedExitCode = failure.exitCode;
+            }
+            result.failedStepLogPath = failure.stepLogPath;
+            result.lastOutputLines = failure.tailLines ?? [];
+        }
+        else {
+            result.lastOutputLines = [];
+        }
+    }
+    return result;
+}

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

@@ -0,0 +1,177 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+// ── parseTimelineSteps ────────────────────────────────────────────────────────
+describe("parseTimelineSteps", () => {
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "result-builder-test-"));
+    });
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it("parses succeeded, failed, and skipped steps", async () => {
+        const { parseTimelineSteps } = await import("./result-builder.js");
+        const timelinePath = path.join(tmpDir, "timeline.json");
+        fs.writeFileSync(timelinePath, JSON.stringify([
+            { type: "Task", name: "Setup", result: "Succeeded" },
+            { type: "Task", name: "Build", result: "Failed" },
+            { type: "Task", name: "Deploy", result: "Skipped" },
+            { type: "Task", name: "Cleanup", state: "completed" },
+        ]));
+        const steps = parseTimelineSteps(timelinePath);
+        expect(steps).toEqual([
+            { name: "Setup", status: "passed" },
+            { name: "Build", status: "failed" },
+            { name: "Deploy", status: "skipped" },
+            { name: "Cleanup", status: "passed" },
+        ]);
+    });
+    it("returns empty array when file does not exist", async () => {
+        const { parseTimelineSteps } = await import("./result-builder.js");
+        expect(parseTimelineSteps(path.join(tmpDir, "nope.json"))).toEqual([]);
+    });
+    it("filters out non-Task records", async () => {
+        const { parseTimelineSteps } = await import("./result-builder.js");
+        const timelinePath = path.join(tmpDir, "timeline.json");
+        fs.writeFileSync(timelinePath, JSON.stringify([
+            { type: "Job", name: "Root" },
+            { type: "Task", name: "Build", result: "succeeded" },
+        ]));
+        const steps = parseTimelineSteps(timelinePath);
+        expect(steps).toHaveLength(1);
+        expect(steps[0].name).toBe("Build");
+    });
+});
+// ── sanitizeStepName ──────────────────────────────────────────────────────────
+describe("sanitizeStepName", () => {
+    it("replaces special characters with hyphens", async () => {
+        const { sanitizeStepName } = await import("./result-builder.js");
+        expect(sanitizeStepName("Run npm test (shard 1/3)")).toBe("Run-npm-test-shard-1-3");
+    });
+    it("collapses multiple hyphens", async () => {
+        const { sanitizeStepName } = await import("./result-builder.js");
+        expect(sanitizeStepName("a   b---c")).toBe("a-b-c");
+    });
+    it("strips leading and trailing hyphens", async () => {
+        const { sanitizeStepName } = await import("./result-builder.js");
+        expect(sanitizeStepName("--test--")).toBe("test");
+    });
+    it("truncates to 80 characters", async () => {
+        const { sanitizeStepName } = await import("./result-builder.js");
+        const long = "a".repeat(100);
+        expect(sanitizeStepName(long).length).toBe(80);
+    });
+});
+// ── extractFailureDetails ─────────────────────────────────────────────────────
+describe("extractFailureDetails", () => {
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "failure-test-"));
+    });
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it("extracts exit code from the issues array", async () => {
+        const { extractFailureDetails } = await import("./result-builder.js");
+        const timelinePath = path.join(tmpDir, "timeline.json");
+        fs.writeFileSync(timelinePath, JSON.stringify([
+            {
+                type: "Task",
+                name: "Build",
+                result: "Failed",
+                issues: [{ type: "error", message: "Process completed with exit code 2" }],
+            },
+        ]));
+        const details = extractFailureDetails(timelinePath, "Build", tmpDir);
+        expect(details.exitCode).toBe(2);
+    });
+    it("finds the step log file via sanitized name", async () => {
+        const { extractFailureDetails } = await import("./result-builder.js");
+        const stepsDir = path.join(tmpDir, "steps");
+        fs.mkdirSync(stepsDir, { recursive: true });
+        fs.writeFileSync(path.join(stepsDir, "Run-tests.log"), "error line 1\nerror line 2\n");
+        const timelinePath = path.join(tmpDir, "timeline.json");
+        fs.writeFileSync(timelinePath, JSON.stringify([
+            {
+                type: "Task",
+                name: "Run tests",
+                result: "Failed",
+                id: "uuid-123",
+            },
+        ]));
+        const details = extractFailureDetails(timelinePath, "Run tests", tmpDir);
+        expect(details.stepLogPath).toBe(path.join(stepsDir, "Run-tests.log"));
+        expect(details.tailLines).toContain("error line 1");
+    });
+    it("returns empty object when no matching record exists", async () => {
+        const { extractFailureDetails } = await import("./result-builder.js");
+        const timelinePath = path.join(tmpDir, "timeline.json");
+        fs.writeFileSync(timelinePath, JSON.stringify([]));
+        const details = extractFailureDetails(timelinePath, "NonExistent", tmpDir);
+        expect(details).toEqual({});
+    });
+});
+// ── buildJobResult ────────────────────────────────────────────────────────────
+describe("buildJobResult", () => {
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "result-test-"));
+    });
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it("builds a successful result", async () => {
+        const { buildJobResult } = await import("./result-builder.js");
+        const timelinePath = path.join(tmpDir, "timeline.json");
+        fs.writeFileSync(timelinePath, JSON.stringify([{ type: "Task", name: "Build", result: "Succeeded" }]));
+        const result = buildJobResult({
+            containerName: "test-runner",
+            job: { workflowPath: "/tmp/ci.yml", taskId: "build" },
+            startTime: Date.now() - 5000,
+            jobSucceeded: true,
+            lastFailedStep: null,
+            containerExitCode: 0,
+            timelinePath,
+            logDir: tmpDir,
+            debugLogPath: path.join(tmpDir, "debug.log"),
+        });
+        expect(result.succeeded).toBe(true);
+        expect(result.name).toBe("test-runner");
+        expect(result.workflow).toBe("ci.yml");
+        expect(result.steps).toHaveLength(1);
+        expect(result.failedStep).toBeUndefined();
+    });
+    it("builds a failed result with failure details", async () => {
+        const { buildJobResult } = await import("./result-builder.js");
+        const timelinePath = path.join(tmpDir, "timeline.json");
+        const stepsDir = path.join(tmpDir, "steps");
+        fs.mkdirSync(stepsDir, { recursive: true });
+        fs.writeFileSync(path.join(stepsDir, "Build.log"), "compile error\nfailed\n");
+        fs.writeFileSync(timelinePath, JSON.stringify([
+            {
+                type: "Task",
+                name: "Build",
+                result: "Failed",
+                issues: [{ type: "error", message: "Process completed with exit code 1" }],
+            },
+        ]));
+        const result = buildJobResult({
+            containerName: "test-runner",
+            job: { workflowPath: "/tmp/ci.yml", taskId: "build" },
+            startTime: Date.now() - 5000,
+            jobSucceeded: false,
+            lastFailedStep: "Build",
+            containerExitCode: 0,
+            timelinePath,
+            logDir: tmpDir,
+            debugLogPath: path.join(tmpDir, "debug.log"),
+        });
+        expect(result.succeeded).toBe(false);
+        expect(result.failedStep).toBe("Build");
+        expect(result.failedExitCode).toBe(1);
+        expect(result.failedStepLogPath).toBe(path.join(stepsDir, "Build.log"));
+        expect(result.lastOutputLines).toContain("compile error");
+    });
+});

package/dist/runner/step-wrapper.js

@@ -0,0 +1,82 @@
+// ─── Pause-on-failure step wrapping ───────────────────────────────────────────
+//
+// Wraps `run:` step scripts in a retry loop so the runner pauses on failure
+// and waits for an external signal (retry / abort) before continuing.
+/**
+ * Wrap a bash script in the pause-on-failure retry loop.
+ *
+ * The wrapper:
+ *  1. Checks for a `from-step` signal file — if present and this step's index
+ *     is below the target, the step is skipped (exit 0). When the target is
+ *     reached the signal file is removed so subsequent steps run normally.
+ *  2. Runs the original script
+ *  3. On success → exits 0
+ *  4. On failure → writes a `paused` signal file, emits a `::error::` annotation,
+ *     and polls until a `retry` or `abort` signal file appears.
+ *
+ * @param stepIndex  1-based index of this step across ALL steps (matches the UI numbering)
+ */
+export function wrapStepScript(script, stepName, stepIndex) {
+    // Escape single-quotes in the step name so it's safe inside the echo
+    const safeName = stepName.replace(/'/g, "'\\''");
+    // The original script runs in a subshell `( ... )` so that:
+    //  1. `exit N` inside the script terminates the subshell, not the retry loop
+    //  2. The runner's `set -e` (bash -e {0}) doesn't bypass the wrapper
+    return `__SIGNALS="/tmp/agent-ci-signals"
+__STEP_INDEX=${stepIndex}
+# ── from-step skip logic ──
+if [ -f "$__SIGNALS/from-step" ]; then
+  __FROM_STEP=$(cat "$__SIGNALS/from-step")
+  if [ "$__FROM_STEP" != '*' ] && [ "$__STEP_INDEX" -lt "$__FROM_STEP" ] 2>/dev/null; then
+    echo "Skipping step $__STEP_INDEX (rewind target: step $__FROM_STEP)"
+    exit 0
+  fi
+  rm -f "$__SIGNALS/from-step"
+  echo "Resuming from step $__STEP_INDEX."
+fi
+__ATTEMPT=0
+while true; do
+  __ATTEMPT=$((__ATTEMPT + 1))
+  set +e
+  (
+    ${script}
+  )
+  __EC=$?
+  set -e
+  if [ $__EC -eq 0 ]; then exit 0; fi
+  printf '%s\\n%s\\n%s' '${safeName}' "$__ATTEMPT" "$__STEP_INDEX" > "$__SIGNALS/paused"
+  echo "::error::Step failed (exit $__EC). Paused — waiting for retry signal."
+  while [ ! -f "$__SIGNALS/retry" ] && [ ! -f "$__SIGNALS/abort" ]; do sleep 1; done
+  if [ -f "$__SIGNALS/abort" ]; then rm -f "$__SIGNALS/abort" "$__SIGNALS/paused"; exit $__EC; fi
+  rm -f "$__SIGNALS/retry" "$__SIGNALS/paused"
+  echo "Retrying step..."
+done`;
+}
+/**
+ * Clone a steps array, wrapping `run:` steps when `pauseOnFailure` is enabled.
+ *
+ * Only steps with `Reference.Type === "Script"` (i.e. `run:` steps) are wrapped.
+ * `uses:` steps are left untouched because the runner's action dispatcher handles
+ * them internally and can't be wrapped at the shell level.
+ *
+ * Step indices are 1-based across ALL steps (matching the tree UI numbering),
+ * not just the `run:` steps.
+ */
+export function wrapJobSteps(steps, pauseOnFailure) {
+    if (!pauseOnFailure || !steps) {
+        return steps;
+    }
+    return steps.map((step, idx) => {
+        if (step?.Reference?.Type !== "Script" || !step?.Inputs?.script) {
+            return step;
+        }
+        const stepIndex = idx + 1; // 1-based to match UI
+        return {
+            ...step,
+            Inputs: {
+                ...step.Inputs,
+                script: wrapStepScript(step.Inputs.script, step.Name || step.DisplayName || "step", stepIndex),
+            },
+        };
+    });
+}

package/dist/runner/step-wrapper.test.js

@@ -0,0 +1,77 @@
+import { describe, it, expect } from "vitest";
+import { wrapStepScript, wrapJobSteps } from "./step-wrapper.js";
+// ── wrapStepScript ────────────────────────────────────────────────────────────
+describe("wrapStepScript", () => {
+    it("wraps the original script in a retry loop", () => {
+        const wrapped = wrapStepScript("npm test", "Run tests", 1);
+        expect(wrapped).toContain("npm test");
+        expect(wrapped).toContain('__SIGNALS="/tmp/agent-ci-signals"');
+        expect(wrapped).toContain("while true; do");
+        expect(wrapped).toContain("Retrying step...");
+    });
+    it("includes the step name in the paused signal", () => {
+        const wrapped = wrapStepScript("echo hi", "My Step", 2);
+        expect(wrapped).toContain('printf \'%s\\n%s\\n%s\' \'My Step\' "$__ATTEMPT" "$__STEP_INDEX" > "$__SIGNALS/paused"');
+    });
+    it("escapes single quotes in step names", () => {
+        const wrapped = wrapStepScript("echo hi", "it's a test", 1);
+        // Should not contain an unescaped single quote that breaks the shell
+        expect(wrapped).toContain("it'\\''s a test");
+    });
+    it("embeds step index for from-step comparison", () => {
+        const wrapped = wrapStepScript("npm test", "Run tests", 3);
+        expect(wrapped).toContain("__STEP_INDEX=3");
+    });
+    it("includes from-step skip logic with numeric comparison", () => {
+        const wrapped = wrapStepScript("npm test", "Run tests", 2);
+        expect(wrapped).toContain('if [ -f "$__SIGNALS/from-step" ]');
+        expect(wrapped).toContain('"$__STEP_INDEX" -lt "$__FROM_STEP"');
+        expect(wrapped).toContain("Skipping step $__STEP_INDEX");
+        expect(wrapped).toContain("Resuming from step $__STEP_INDEX.");
+    });
+    it("supports wildcard * for --from-start", () => {
+        const wrapped = wrapStepScript("npm test", "My Step", 1);
+        expect(wrapped).toContain(`"$__FROM_STEP" != '*'`);
+    });
+});
+// ── wrapJobSteps ──────────────────────────────────────────────────────────────
+describe("wrapJobSteps", () => {
+    const scriptStep = {
+        Name: "Run tests",
+        Reference: { Type: "Script" },
+        Inputs: { script: "npm test" },
+    };
+    const usesStep = {
+        Name: "Checkout",
+        Reference: { Type: "Repository", Name: "actions/checkout" },
+        Inputs: {},
+    };
+    it("returns steps unchanged when pauseOnFailure is false", () => {
+        const result = wrapJobSteps([scriptStep, usesStep], false);
+        expect(result).toEqual([scriptStep, usesStep]);
+    });
+    it("wraps run: steps when pauseOnFailure is true", () => {
+        const result = wrapJobSteps([scriptStep, usesStep], true);
+        expect(result[0].Inputs.script).toContain("__SIGNALS");
+        expect(result[0].Inputs.script).toContain("npm test");
+    });
+    it("leaves uses: steps untouched", () => {
+        const result = wrapJobSteps([scriptStep, usesStep], true);
+        expect(result[1]).toEqual(usesStep);
+    });
+    it("handles undefined/empty steps gracefully", () => {
+        expect(wrapJobSteps([], true)).toEqual([]);
+        expect(wrapJobSteps(undefined, false)).toBeUndefined();
+    });
+    it("assigns correct 1-based step indices", () => {
+        // uses step at index 0 (step 1), script at index 1 (step 2)
+        const result = wrapJobSteps([usesStep, scriptStep], true);
+        expect(result[1].Inputs.script).toContain("__STEP_INDEX=2");
+    });
+    it("assigns sequential indices across multiple script steps", () => {
+        const step2 = { ...scriptStep, Name: "Build" };
+        const result = wrapJobSteps([scriptStep, step2], true);
+        expect(result[0].Inputs.script).toContain("__STEP_INDEX=1");
+        expect(result[1].Inputs.script).toContain("__STEP_INDEX=2");
+    });
+});