@redwoodjs/agent-ci 0.1.0

package/dist/output/logger.js

@@ -0,0 +1,57 @@
+import path from "path";
+import fs from "fs";
+import { getWorkingDirectory } from "./working-directory.js";
+/** Root of all run directories: `<workingDir>/runs/` */
+function getRunsDir() {
+    return path.join(getWorkingDirectory(), "runs");
+}
+export function ensureLogDirs() {
+    fs.mkdirSync(getRunsDir(), { recursive: true });
+}
+export function getNextLogNum(prefix) {
+    const runsDir = getRunsDir();
+    if (!fs.existsSync(runsDir)) {
+        return 1;
+    }
+    const items = fs.readdirSync(runsDir, { withFileTypes: true });
+    const nums = items
+        .filter((item) => item.isDirectory() && item.name.startsWith(`${prefix}-`))
+        .map((item) => {
+        // Extract the trailing numeric run counter from a name like:
+        //   agent-ci-redwoodjssdk-14        → 14
+        //   agent-ci-redwoodjssdk-15-j1     → 15
+        //   agent-ci-redwoodjssdk-15-j1-m2  → 15
+        // Strategy: strip any -j<N>, -m<N>, -r<N> suffixes first, then grab the last number.
+        const baseName = item.name
+            .replace(/-j\d+(-m\d+)?(-r\d+)?$/, "")
+            .replace(/-m\d+(-r\d+)?$/, "")
+            .replace(/-r\d+$/, "");
+        const match = baseName.match(/-(\d+)$/);
+        return match ? parseInt(match[1], 10) : 0;
+    });
+    return nums.length > 0 ? Math.max(...nums) + 1 : 1;
+}
+export function createLogContext(prefix, preferredName) {
+    ensureLogDirs();
+    let num = 0;
+    let name = preferredName;
+    if (!name) {
+        num = getNextLogNum(prefix);
+        name = `${prefix}-${num}`;
+    }
+    const runDir = path.join(getRunsDir(), name);
+    const logDir = path.join(runDir, "logs");
+    fs.mkdirSync(logDir, { recursive: true });
+    return {
+        num,
+        name,
+        runDir,
+        logDir,
+        outputLogPath: path.join(logDir, "output.log"),
+        debugLogPath: path.join(logDir, "debug.log"),
+    };
+}
+export function finalizeLog(logPath, _exitCode, _commitSha, _preferredName) {
+    // Log file stays in place; just return the path as-is.
+    return logPath;
+}

package/dist/output/logger.test.js

@@ -0,0 +1,82 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+describe("Logger utilities", () => {
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "agent-ci-logger-test-"));
+        vi.resetModules();
+    });
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+        vi.restoreAllMocks();
+    });
+    describe("ensureLogDirs", () => {
+        it("creates the runs/ directory", async () => {
+            const { setWorkingDirectory } = await import("./working-directory.js");
+            const { ensureLogDirs } = await import("./logger.js");
+            setWorkingDirectory(tmpDir);
+            ensureLogDirs();
+            expect(fs.existsSync(path.join(tmpDir, "runs"))).toBe(true);
+        });
+    });
+    describe("getNextLogNum", () => {
+        it("returns 1 when runs/ dir is empty or absent", async () => {
+            const { setWorkingDirectory } = await import("./working-directory.js");
+            const { getNextLogNum } = await import("./logger.js");
+            setWorkingDirectory(tmpDir);
+            expect(getNextLogNum("agent-ci")).toBe(1);
+        });
+        it("returns next number after existing agent-ci-* entries", async () => {
+            const { setWorkingDirectory } = await import("./working-directory.js");
+            const { getNextLogNum } = await import("./logger.js");
+            setWorkingDirectory(tmpDir);
+            fs.mkdirSync(path.join(tmpDir, "runs", "agent-ci-1"), { recursive: true });
+            fs.mkdirSync(path.join(tmpDir, "runs", "agent-ci-2"), { recursive: true });
+            expect(getNextLogNum("agent-ci")).toBe(3);
+        });
+        it("counts only the base run number from multi-job names", async () => {
+            const { setWorkingDirectory } = await import("./working-directory.js");
+            const { getNextLogNum } = await import("./logger.js");
+            setWorkingDirectory(tmpDir);
+            // Multi-job run: agent-ci-15 with -j1-m2 suffix — base is 15
+            fs.mkdirSync(path.join(tmpDir, "runs", "agent-ci-redwoodjssdk-14"), { recursive: true });
+            fs.mkdirSync(path.join(tmpDir, "runs", "agent-ci-redwoodjssdk-15-j1"), { recursive: true });
+            fs.mkdirSync(path.join(tmpDir, "runs", "agent-ci-redwoodjssdk-15-j2-m1"), {
+                recursive: true,
+            });
+            expect(getNextLogNum("agent-ci")).toBe(16);
+        });
+    });
+    describe("createLogContext", () => {
+        it("creates runDir/logs/ and returns correct paths", async () => {
+            const { setWorkingDirectory } = await import("./working-directory.js");
+            const { createLogContext } = await import("./logger.js");
+            setWorkingDirectory(tmpDir);
+            const ctx = createLogContext("agent-ci");
+            expect(ctx.name).toMatch(/^agent-ci-\d+$/);
+            expect(fs.existsSync(ctx.runDir)).toBe(true);
+            expect(fs.existsSync(ctx.logDir)).toBe(true);
+            expect(ctx.outputLogPath).toBe(path.join(ctx.logDir, "output.log"));
+            expect(ctx.debugLogPath).toBe(path.join(ctx.logDir, "debug.log"));
+        });
+        it("uses preferredName when provided", async () => {
+            const { setWorkingDirectory } = await import("./working-directory.js");
+            const { createLogContext } = await import("./logger.js");
+            setWorkingDirectory(tmpDir);
+            const ctx = createLogContext("agent-ci", "agent-ci-redwoodjssdk-42");
+            expect(ctx.name).toBe("agent-ci-redwoodjssdk-42");
+            expect(ctx.runDir).toBe(path.join(tmpDir, "runs", "agent-ci-redwoodjssdk-42"));
+            expect(ctx.logDir).toBe(path.join(tmpDir, "runs", "agent-ci-redwoodjssdk-42", "logs"));
+        });
+        it("auto-increments when no preferredName given", async () => {
+            const { setWorkingDirectory } = await import("./working-directory.js");
+            const { createLogContext } = await import("./logger.js");
+            setWorkingDirectory(tmpDir);
+            const first = createLogContext("agent-ci");
+            const second = createLogContext("agent-ci");
+            expect(second.num).toBe(first.num + 1);
+        });
+    });
+});

package/dist/output/reporter.js

@@ -0,0 +1,67 @@
+import fs from "fs";
+// ─── Formatting helpers ───────────────────────────────────────────────────────
+function formatDuration(ms) {
+    const s = Math.round(ms / 1000);
+    if (s < 60) {
+        return `${s}s`;
+    }
+    const m = Math.floor(s / 60);
+    const rem = s % 60;
+    return rem > 0 ? `${m}m ${rem}s` : `${m}m`;
+}
+// ─── Failures-first summary (emitted after all jobs complete) ─────────────────
+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");
+        for (const f of failures) {
+            if (f.failedStep) {
+                process.stdout.write(`  ✗ ${f.workflow} > ${f.taskId} > "${f.failedStep}"\n`);
+            }
+            else {
+                process.stdout.write(`  ✗ ${f.workflow} > ${f.taskId}\n`);
+            }
+            if (f.failedExitCode !== undefined) {
+                process.stdout.write(`    Exit code: ${f.failedExitCode}\n`);
+            }
+            if (f.lastOutputLines && f.lastOutputLines.length > 0) {
+                process.stdout.write(`    Last output:\n`);
+                for (const line of f.lastOutputLines) {
+                    process.stdout.write(`      ${line}\n`);
+                }
+            }
+            process.stdout.write("\n");
+        }
+    }
+    process.stdout.write("\n━━━ SUMMARY ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n");
+    const status = failures.length > 0
+        ? `✗ ${failures.length} failed, ${passes.length} passed`
+        : `✓ ${passes.length} passed`;
+    process.stdout.write(`  Status:    ${status} (${results.length} total)\n`);
+    process.stdout.write(`  Duration:  ${formatDuration(totalMs)}\n`);
+    if (runDir) {
+        process.stdout.write(`  Root:      ${runDir}\n`);
+    }
+    process.stdout.write("\n");
+}
+// ─── Tail helper ──────────────────────────────────────────────────────────────
+/** Read the last N lines from a log file. */
+export function tailLogFile(filePath, lineCount = 20) {
+    try {
+        if (!fs.existsSync(filePath)) {
+            return [];
+        }
+        const content = fs.readFileSync(filePath, "utf-8");
+        const lines = content.split("\n");
+        // Trim trailing empty lines
+        while (lines.length > 0 && lines[lines.length - 1].trim() === "") {
+            lines.pop();
+        }
+        return lines.slice(-lineCount);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/output/run-state.js

@@ -0,0 +1,126 @@
+import fs from "fs";
+import path from "path";
+export class RunStateStore {
+    state;
+    filePath;
+    listeners = [];
+    constructor(runId, filePath) {
+        this.state = {
+            runId,
+            status: "running",
+            startedAt: new Date().toISOString(),
+            workflows: [],
+        };
+        this.filePath = filePath;
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    }
+    /** Register a callback that fires synchronously on every state change. */
+    onUpdate(listener) {
+        this.listeners.push(listener);
+    }
+    getState() {
+        return this.state;
+    }
+    /**
+     * Register a job under a workflow (creating the workflow entry if needed).
+     * Call this before executing the job so the render loop can show it immediately.
+     */
+    addJob(workflowPath, jobId, runnerId, options) {
+        let wf = this.state.workflows.find((w) => w.path === workflowPath);
+        if (!wf) {
+            wf = {
+                id: path.basename(workflowPath),
+                path: workflowPath,
+                status: "queued",
+                jobs: [],
+            };
+            this.state.workflows.push(wf);
+        }
+        if (!wf.jobs.some((j) => j.runnerId === runnerId)) {
+            wf.jobs.push({
+                id: jobId,
+                runnerId,
+                status: "queued",
+                steps: [],
+                ...options,
+            });
+        }
+        this.notify();
+    }
+    /**
+     * Update fields on a job (matched by runnerId).
+     * Automatically syncs parent workflow status and saves to disk.
+     */
+    updateJob(runnerId, updates) {
+        for (const wf of this.state.workflows) {
+            const job = wf.jobs.find((j) => j.runnerId === runnerId);
+            if (job) {
+                Object.assign(job, updates);
+                this.syncWorkflowStatus(wf);
+                break;
+            }
+        }
+        this.save();
+        this.notify();
+    }
+    /** Mark the overall run complete and persist. */
+    complete(status) {
+        this.state.status = status;
+        this.state.completedAt = new Date().toISOString();
+        this.save();
+    }
+    /**
+     * Atomically write state to disk.
+     * Uses write-tmp-then-rename to prevent corruption on concurrent reads.
+     */
+    save() {
+        try {
+            const tmp = this.filePath + ".tmp";
+            fs.writeFileSync(tmp, JSON.stringify(this.state, null, 2));
+            fs.renameSync(tmp, this.filePath);
+        }
+        catch {
+            // Best-effort — rendering uses in-memory state, not disk
+        }
+    }
+    /** Load a previously-written RunState from disk. */
+    static load(filePath) {
+        try {
+            return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+        }
+        catch {
+            return JSON.parse(fs.readFileSync(filePath + ".tmp", "utf-8"));
+        }
+    }
+    notify() {
+        for (const listener of this.listeners) {
+            try {
+                listener(this.state);
+            }
+            catch {
+                // Best-effort — don't let listener errors break state updates
+            }
+        }
+    }
+    syncWorkflowStatus(wf) {
+        const statuses = wf.jobs.map((j) => j.status);
+        if (statuses.length === 0) {
+            return;
+        }
+        if (statuses.every((s) => s === "completed")) {
+            wf.status = "completed";
+            if (!wf.completedAt) {
+                wf.completedAt = new Date().toISOString();
+            }
+        }
+        else if (statuses.some((s) => s === "failed")) {
+            wf.status = "failed";
+        }
+        else if (statuses.some((s) => s === "running" || s === "booting" || s === "paused")) {
+            wf.status = "running";
+            if (!wf.startedAt) {
+                wf.startedAt = new Date().toISOString();
+            }
+        }
+    }
+}

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

@@ -0,0 +1,169 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { RunStateStore } from "./run-state.js";
+let tmpDir;
+beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "run-state-test-"));
+});
+afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+function makeStore(runId = "test-run-1") {
+    return new RunStateStore(runId, path.join(tmpDir, runId, "run-state.json"));
+}
+describe("RunStateStore", () => {
+    it("initialises with an empty running state", () => {
+        const store = makeStore();
+        const state = store.getState();
+        expect(state.status).toBe("running");
+        expect(state.workflows).toEqual([]);
+        expect(state.runId).toBe("test-run-1");
+        expect(state.startedAt).toMatch(/^\d{4}-/); // ISO date
+    });
+    it("addJob creates a workflow entry and adds a job", () => {
+        const store = makeStore();
+        store.addJob("/repo/.github/workflows/ci.yml", "test", "agent-ci-1");
+        const state = store.getState();
+        expect(state.workflows).toHaveLength(1);
+        expect(state.workflows[0].id).toBe("ci.yml");
+        expect(state.workflows[0].jobs).toHaveLength(1);
+        expect(state.workflows[0].jobs[0].id).toBe("test");
+        expect(state.workflows[0].jobs[0].runnerId).toBe("agent-ci-1");
+        expect(state.workflows[0].jobs[0].status).toBe("queued");
+    });
+    it("addJob appends to an existing workflow", () => {
+        const store = makeStore();
+        store.addJob("/repo/.github/workflows/ci.yml", "lint", "agent-ci-1-j1");
+        store.addJob("/repo/.github/workflows/ci.yml", "test", "agent-ci-1-j2");
+        const wf = store.getState().workflows[0];
+        expect(wf.jobs).toHaveLength(2);
+        expect(wf.jobs[0].id).toBe("lint");
+        expect(wf.jobs[1].id).toBe("test");
+    });
+    it("addJob ignores duplicate runnerId", () => {
+        const store = makeStore();
+        store.addJob("/repo/.github/workflows/ci.yml", "test", "agent-ci-1");
+        store.addJob("/repo/.github/workflows/ci.yml", "test", "agent-ci-1");
+        expect(store.getState().workflows[0].jobs).toHaveLength(1);
+    });
+    it("updateJob updates the correct job", () => {
+        const store = makeStore();
+        store.addJob("/repo/.github/workflows/ci.yml", "test", "agent-ci-1");
+        store.updateJob("agent-ci-1", { status: "booting", startedAt: "2024-01-01T00:00:00Z" });
+        const job = store.getState().workflows[0].jobs[0];
+        expect(job.status).toBe("booting");
+        expect(job.startedAt).toBe("2024-01-01T00:00:00Z");
+    });
+    it("updateJob syncs workflow status to running when a job boots", () => {
+        const store = makeStore();
+        store.addJob("/repo/.github/workflows/ci.yml", "test", "agent-ci-1");
+        store.updateJob("agent-ci-1", { status: "booting" });
+        expect(store.getState().workflows[0].status).toBe("running");
+    });
+    it("updateJob syncs workflow status to completed when all jobs complete", () => {
+        const store = makeStore();
+        store.addJob("/repo/.github/workflows/ci.yml", "lint", "agent-ci-1-j1");
+        store.addJob("/repo/.github/workflows/ci.yml", "test", "agent-ci-1-j2");
+        store.updateJob("agent-ci-1-j1", { status: "completed" });
+        store.updateJob("agent-ci-1-j2", { status: "completed" });
+        expect(store.getState().workflows[0].status).toBe("completed");
+    });
+    it("updateJob syncs workflow status to failed when any job fails", () => {
+        const store = makeStore();
+        store.addJob("/repo/.github/workflows/ci.yml", "lint", "agent-ci-1-j1");
+        store.addJob("/repo/.github/workflows/ci.yml", "test", "agent-ci-1-j2");
+        store.updateJob("agent-ci-1-j1", { status: "failed" });
+        store.updateJob("agent-ci-1-j2", { status: "completed" });
+        expect(store.getState().workflows[0].status).toBe("failed");
+    });
+    it("updateJob handles pause state", () => {
+        const store = makeStore();
+        store.addJob("/repo/.github/workflows/ci.yml", "test", "agent-ci-1");
+        store.updateJob("agent-ci-1", {
+            status: "paused",
+            pausedAtStep: "Run tests",
+            pausedAtMs: "2024-01-01T00:01:00Z",
+            attempt: 1,
+            lastOutputLines: ["Error: test failed"],
+        });
+        const job = store.getState().workflows[0].jobs[0];
+        expect(job.status).toBe("paused");
+        expect(job.pausedAtStep).toBe("Run tests");
+        expect(job.attempt).toBe(1);
+        expect(job.lastOutputLines).toEqual(["Error: test failed"]);
+    });
+    it("complete marks the run as completed", () => {
+        const store = makeStore();
+        store.complete("completed");
+        const state = store.getState();
+        expect(state.status).toBe("completed");
+        expect(state.completedAt).toBeDefined();
+    });
+    it("complete marks the run as failed", () => {
+        const store = makeStore();
+        store.complete("failed");
+        expect(store.getState().status).toBe("failed");
+    });
+    describe("atomic persistence", () => {
+        it("save writes a valid JSON file", () => {
+            const store = makeStore("persist-test");
+            store.addJob("/repo/.github/workflows/ci.yml", "test", "agent-ci-1");
+            store.save();
+            const filePath = path.join(tmpDir, "persist-test", "run-state.json");
+            expect(fs.existsSync(filePath)).toBe(true);
+            const parsed = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+            expect(parsed.runId).toBe("persist-test");
+            expect(parsed.workflows).toHaveLength(1);
+        });
+        it("load round-trips the state from disk", () => {
+            const store = makeStore("roundtrip");
+            store.addJob("/repo/.github/workflows/ci.yml", "test", "agent-ci-1");
+            store.updateJob("agent-ci-1", { status: "running" });
+            store.save();
+            const filePath = path.join(tmpDir, "roundtrip", "run-state.json");
+            const loaded = RunStateStore.load(filePath);
+            expect(loaded.runId).toBe("roundtrip");
+            expect(loaded.workflows[0].jobs[0].status).toBe("running");
+        });
+        it("save does not leave .tmp files behind", () => {
+            const store = makeStore("no-tmp");
+            store.save();
+            const dir = path.join(tmpDir, "no-tmp");
+            const files = fs.readdirSync(dir);
+            expect(files.some((f) => f.endsWith(".tmp"))).toBe(false);
+        });
+    });
+    describe("matrix jobs", () => {
+        it("supports multiple matrix combinations under one workflow", () => {
+            const store = makeStore();
+            store.addJob("/repo/.github/workflows/ci.yml", "test", "agent-ci-1-j1-m1", {
+                matrixValues: { node: "18" },
+            });
+            store.addJob("/repo/.github/workflows/ci.yml", "test", "agent-ci-1-j1-m2", {
+                matrixValues: { node: "20" },
+            });
+            const wf = store.getState().workflows[0];
+            expect(wf.jobs).toHaveLength(2);
+            expect(wf.jobs[0].matrixValues).toEqual({ node: "18" });
+            expect(wf.jobs[1].matrixValues).toEqual({ node: "20" });
+        });
+    });
+    describe("step state", () => {
+        it("can update job with steps array", () => {
+            const store = makeStore();
+            store.addJob("/repo/.github/workflows/ci.yml", "test", "agent-ci-1");
+            store.updateJob("agent-ci-1", {
+                steps: [
+                    { name: "Set up job", index: 1, status: "completed", durationMs: 1000 },
+                    { name: "Run tests", index: 2, status: "running", startedAt: new Date().toISOString() },
+                ],
+            });
+            const job = store.getState().workflows[0].jobs[0];
+            expect(job.steps).toHaveLength(2);
+            expect(job.steps[0].status).toBe("completed");
+            expect(job.steps[1].status).toBe("running");
+        });
+    });
+});

package/dist/output/state-renderer.js

@@ -0,0 +1,149 @@
+// ─── State Renderer ───────────────────────────────────────────────────────────
+// Pure function: RunState → string.
+// The render loop in cli.ts calls this on every tick and passes the result to
+// logUpdate. No side effects, no I/O — fully testable in isolation.
+import path from "path";
+import { renderTree } from "./tree-renderer.js";
+// ─── ANSI helpers ─────────────────────────────────────────────────────────────
+const YELLOW = `${String.fromCharCode(27)}[33m`;
+const DIM = `${String.fromCharCode(27)}[2m`;
+const RESET = `${String.fromCharCode(27)}[0m`;
+// ─── Spinner ──────────────────────────────────────────────────────────────────
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+function getSpinnerFrame() {
+    return SPINNER_FRAMES[Math.floor(Date.now() / 80) % SPINNER_FRAMES.length];
+}
+// ─── Formatting ───────────────────────────────────────────────────────────────
+function fmtMs(ms) {
+    return ms >= 1000 ? `${(ms / 1000).toFixed(1)}s` : `${ms}ms`;
+}
+// ─── Step node builder ────────────────────────────────────────────────────────
+function buildStepNode(step, job, padW) {
+    const pad = (n) => String(n).padStart(padW);
+    const dur = step.durationMs !== undefined ? ` (${Math.round(step.durationMs / 1000)}s)` : "";
+    switch (step.status) {
+        case "running": {
+            const elapsed = step.startedAt
+                ? Math.round((Date.now() - new Date(step.startedAt).getTime()) / 1000)
+                : 0;
+            const frame = getSpinnerFrame();
+            // Retrying (was paused, now running again on same step)
+            if ((job.attempt ?? 0) > 0 && job.pausedAtStep === step.name) {
+                return { label: `${frame} ${pad(step.index)}. ${step.name} — retrying (${elapsed}s...)` };
+            }
+            return { label: `${frame} ${pad(step.index)}. ${step.name} (${elapsed}s...)` };
+        }
+        case "paused": {
+            const frozenElapsed = job.pausedAtMs && step.startedAt
+                ? Math.round((new Date(job.pausedAtMs).getTime() - new Date(step.startedAt).getTime()) / 1000)
+                : step.startedAt
+                    ? Math.round((Date.now() - new Date(step.startedAt).getTime()) / 1000)
+                    : 0;
+            return {
+                label: `⏸ ${pad(step.index)}. ${step.name} (${frozenElapsed}s)`,
+                children: [{ label: `${YELLOW}Step failed attempt #${job.attempt ?? 1}${RESET}` }],
+            };
+        }
+        case "failed":
+            return { label: `✗ ${pad(step.index)}. ${step.name}${dur}` };
+        case "skipped":
+            return { label: `⊘ ${pad(step.index)}. ${step.name}${dur}` };
+        case "completed":
+            return { label: `✓ ${pad(step.index)}. ${step.name}${dur}` };
+        case "pending":
+        default:
+            return { label: `○ ${pad(step.index)}. ${step.name}` };
+    }
+}
+// ─── Job node builder ─────────────────────────────────────────────────────────
+/**
+ * Build the TreeNode(s) for a job.
+ *
+ * - `singleJobMode`: true when there is exactly one job across all workflows.
+ *   In this mode the "Starting runner" node is shown alongside the job node,
+ *   matching the pre-refactor single-workflow rendering.
+ */
+function buildJobNodes(job, singleJobMode) {
+    // ── Booting (container starting, no timeline yet) ──────────────────────────
+    if (job.status === "booting") {
+        const elapsed = job.startedAt
+            ? Math.round((Date.now() - new Date(job.startedAt).getTime()) / 1000)
+            : 0;
+        const bootNode = {
+            label: `${getSpinnerFrame()} Starting runner ${job.runnerId} (${elapsed}s)`,
+        };
+        if (job.logDir) {
+            bootNode.children = [{ label: `${DIM}Logs: ${job.logDir}${RESET}` }];
+        }
+        return [bootNode];
+    }
+    // ── Completed / failed in multi-job mode → collapse to one line ────────────
+    if (!singleJobMode && (job.status === "completed" || job.status === "failed")) {
+        const icon = job.failedStep ? "✗" : "✓";
+        const dur = job.durationMs !== undefined ? ` (${Math.round(job.durationMs / 1000)}s)` : "";
+        return [{ label: `${icon} ${job.id} ${DIM}${job.runnerId}${RESET}${dur}` }];
+    }
+    // ── Build step nodes ───────────────────────────────────────────────────────
+    const padW = String(job.steps.length).length;
+    const stepNodes = job.steps.map((step) => buildStepNode(step, job, padW));
+    // Retry hint in multi-job paused mode (shown as a child node)
+    if (!singleJobMode && job.status === "paused" && job.pausedAtStep) {
+        stepNodes.push({
+            label: `${YELLOW}↻ retry: agent-ci retry --runner ${job.runnerId}${RESET}`,
+        });
+    }
+    // ── Single-job mode: show "Starting runner" alongside job node ─────────────
+    if (singleJobMode) {
+        const bootLabel = job.bootDurationMs !== undefined
+            ? `Starting runner ${job.runnerId} (${fmtMs(job.bootDurationMs)})`
+            : `Starting runner ${job.runnerId}`;
+        const bootNode = { label: bootLabel };
+        if (job.logDir) {
+            bootNode.children = [{ label: `${DIM}Logs: ${job.logDir}${RESET}` }];
+        }
+        return [bootNode, { label: job.id, children: stepNodes }];
+    }
+    // ── Multi-job mode: show job name with steps as children ──────────────────
+    return [{ label: `${job.id} ${DIM}${job.runnerId}${RESET}`, children: stepNodes }];
+}
+// ─── Main renderer ────────────────────────────────────────────────────────────
+/**
+ * Render the full run state into a string for display via logUpdate.
+ *
+ * This is a pure function: given the same RunState and the same wall-clock time
+ * it always produces the same output. Spinner frames are derived from Date.now().
+ */
+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;
+    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;
+            }
+        }
+        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;
+        if (lastOutputLines && lastOutputLines.length > 0) {
+            output += `\n\n  ${DIM}Last output:${RESET}`;
+            for (const line of lastOutputLines) {
+                const trimmed = line.trimEnd();
+                if (trimmed) {
+                    output += `\n    ${DIM}${trimmed}${RESET}`;
+                }
+            }
+        }
+        output += `\n\n  ${YELLOW}↻ To retry:  agent-ci retry --runner ${runnerId} [enter]${RESET}`;
+        output += `\n  ${YELLOW}■ To abort:  agent-ci abort --runner ${runnerId}${RESET}`;
+    }
+    return output;
+}