@redwoodjs/agent-ci 0.1.0

package/dist/output/cleanup.js

@@ -0,0 +1,218 @@
+import path from "node:path";
+import fs from "node:fs";
+import crypto from "node:crypto";
+import { execFileSync, execSync, spawnSync } from "node:child_process";
+/**
+ * Copy workspace files from a git repo root to dest using git ls-files.
+ * On macOS: uses per-file `cp -c` (APFS CoW clones) for zero-disk copies.
+ * On Linux: uses rsync with file list from git ls-files.
+ * Fallback: Node.js fs.cpSync when neither is available.
+ *
+ * Only copies tracked + untracked-but-not-gitignored files (respects .gitignore).
+ * File paths are never interpolated into shell strings — arguments are always
+ * passed as arrays to avoid shell injection.
+ */
+export function copyWorkspace(repoRoot, dest) {
+    // Get the list of files to copy from git (NUL-separated for safety with
+    // paths that contain spaces or special characters).
+    const files = execSync("git ls-files --cached --others --exclude-standard -z", {
+        stdio: "pipe",
+        cwd: repoRoot,
+    })
+        .toString()
+        .split("\0")
+        .filter(Boolean);
+    if (process.platform === "darwin") {
+        // On macOS with APFS, use per-file cp -c (CoW clone) via execFileSync so
+        // file names are never interpreted by a shell.
+        for (const file of files) {
+            const src = path.join(repoRoot, file);
+            const fileDest = path.join(dest, file);
+            try {
+                fs.mkdirSync(path.dirname(fileDest), { recursive: true });
+                // Try CoW clone first; fall back to regular copy.
+                const result = spawnSync("cp", ["-c", src, fileDest], { stdio: "pipe" });
+                if (result.status !== 0) {
+                    execFileSync("cp", [src, fileDest], { stdio: "pipe" });
+                }
+            }
+            catch {
+                // Skip files that can't be copied (e.g. broken symlinks)
+            }
+        }
+    }
+    else {
+        // Linux/other: pass the file list to rsync via stdin (--files-from=-)
+        // with --from0 so NUL-delimited names are handled correctly.
+        // dest is passed as a positional argument, never shell-interpolated.
+        const input = files.join("\0");
+        const result = spawnSync("rsync", ["-a", "--files-from=-", "--from0", "./", dest + "/"], {
+            input,
+            stdio: ["pipe", "pipe", "pipe"],
+            cwd: repoRoot,
+        });
+        if (result.status !== 0) {
+            // rsync not available — fall through to Node.js fallback
+            copyViaNodeFs(repoRoot, dest, files);
+        }
+    }
+}
+/** Node.js fallback: copy each file individually using fs.cpSync. */
+function copyViaNodeFs(repoRoot, dest, files) {
+    for (const file of files) {
+        const src = path.join(repoRoot, file);
+        const fileDest = path.join(dest, file);
+        try {
+            fs.mkdirSync(path.dirname(fileDest), { recursive: true });
+            fs.cpSync(src, fileDest, { force: true, recursive: true });
+        }
+        catch {
+            // Skip files that can't be copied (e.g. broken symlinks)
+        }
+    }
+}
+/**
+ * All supported lockfile names, in priority order.
+ * The first one found is used as the cache key source.
+ */
+const LOCKFILE_NAMES = [
+    "pnpm-lock.yaml",
+    "package-lock.json",
+    "yarn.lock",
+    "bun.lock",
+    "bun.lockb",
+];
+/**
+ * Compute a short SHA-256 hash of lockfiles tracked in the repo.
+ * Searches for all known lockfile types (pnpm, npm, yarn, bun) and hashes
+ * whichever are found. Used as a cache key for the warm node_modules directory
+ * so the snapshot is automatically invalidated when dependencies change.
+ *
+ * Returns "no-lockfile" if no lockfile is found.
+ */
+export function computeLockfileHash(repoRoot) {
+    // Build a git ls-files query that matches all known lockfile names
+    const patterns = LOCKFILE_NAMES.flatMap((name) => [`'**/${name}'`, `'${name}'`]);
+    let lockfiles;
+    try {
+        lockfiles = execSync(`git ls-files --cached -- ${patterns.join(" ")}`, {
+            stdio: "pipe",
+            cwd: repoRoot,
+        })
+            .toString()
+            .split("\n")
+            .map((f) => f.trim())
+            .filter(Boolean);
+    }
+    catch {
+        lockfiles = [];
+    }
+    if (lockfiles.length === 0) {
+        // Also try a direct filesystem check for untracked lockfiles
+        for (const name of LOCKFILE_NAMES) {
+            const rootLockfile = path.join(repoRoot, name);
+            if (fs.existsSync(rootLockfile)) {
+                lockfiles = [name];
+                break;
+            }
+        }
+        if (lockfiles.length === 0) {
+            return "no-lockfile";
+        }
+    }
+    const hash = crypto.createHash("sha256");
+    for (const file of lockfiles.sort()) {
+        try {
+            hash.update(fs.readFileSync(path.join(repoRoot, file)));
+        }
+        catch {
+            // Skip unreadable files
+        }
+    }
+    return hash.digest("hex").slice(0, 16);
+}
+/**
+ * Sentinel files written by each package manager after a successful install.
+ * If at least one exists, the cache is considered intact.
+ */
+const INSTALL_SENTINELS = [
+    ".modules.yaml", // pnpm
+    ".package-lock.json", // npm
+    ".yarn-integrity", // yarn
+];
+/**
+ * Check whether any known install sentinel exists in the directory.
+ * Each PM writes a specific marker file after a successful install.
+ * For Bun, having any `node_modules/.cache` is sufficient since Bun
+ * does not write a top-level sentinel but always creates a cache dir.
+ */
+export function hasInstallSentinel(warmDir) {
+    for (const sentinel of INSTALL_SENTINELS) {
+        if (fs.existsSync(path.join(warmDir, sentinel))) {
+            return true;
+        }
+    }
+    // Bun: no top-level sentinel, but .cache is reliably created
+    if (fs.existsSync(path.join(warmDir, ".cache"))) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Check whether a warm node_modules directory is populated AND intact.
+ * Used by the wave scheduler to decide whether to serialize the first job.
+ *
+ * A cache is considered warm only if:
+ *   1. The directory exists and is non-empty
+ *   2. At least one install sentinel exists (PM-specific marker file)
+ *
+ * A non-empty directory WITHOUT any sentinel indicates an interrupted install
+ * and is treated as cold/broken.
+ */
+export function isWarmNodeModules(warmDir) {
+    try {
+        if (!fs.existsSync(warmDir)) {
+            return false;
+        }
+        const entries = fs.readdirSync(warmDir);
+        if (entries.length === 0) {
+            return false;
+        }
+        return hasInstallSentinel(warmDir);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Detect and repair a corrupted warm cache directory.
+ * A cache is corrupt if it has files but no install sentinel from any PM.
+ *
+ * When corruption is detected, the directory is deleted and recreated empty
+ * so the next install starts from scratch.
+ *
+ * @returns `"repaired"` if a broken cache was nuked, `"warm"` if the cache
+ *          is healthy, or `"cold"` if it was already empty/missing.
+ */
+export function repairWarmCache(warmDir) {
+    try {
+        if (!fs.existsSync(warmDir)) {
+            return "cold";
+        }
+        const entries = fs.readdirSync(warmDir);
+        if (entries.length === 0) {
+            return "cold";
+        }
+        // If any install sentinel exists, the cache is healthy.
+        if (hasInstallSentinel(warmDir)) {
+            return "warm";
+        }
+        // Non-empty but no sentinel → interrupted install. Nuke and recreate.
+        fs.rmSync(warmDir, { recursive: true, force: true });
+        fs.mkdirSync(warmDir, { recursive: true, mode: 0o777 });
+        return "repaired";
+    }
+    catch {
+        return "cold";
+    }
+}

package/dist/output/cleanup.test.js

@@ -0,0 +1,241 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { execSync } from "node:child_process";
+// ── Workspace copy tests ──────────────────────────────────────────────────────
+describe("copyWorkspace", () => {
+    let repoDir;
+    let destDir;
+    beforeEach(() => {
+        // Create a real git repo with tracked, untracked, and gitignored files
+        repoDir = fs.mkdtempSync(path.join(os.tmpdir(), "oa-copy-test-repo-"));
+        destDir = fs.mkdtempSync(path.join(os.tmpdir(), "oa-copy-test-dest-"));
+        // Init git repo
+        execSync("git init", { cwd: repoDir, stdio: "pipe" });
+        execSync('git config user.name "test"', { cwd: repoDir, stdio: "pipe" });
+        execSync('git config user.email "test@test.com"', { cwd: repoDir, stdio: "pipe" });
+        // Create tracked files
+        fs.writeFileSync(path.join(repoDir, "README.md"), "# Hello");
+        fs.mkdirSync(path.join(repoDir, "src"), { recursive: true });
+        fs.writeFileSync(path.join(repoDir, "src", "index.ts"), "console.log('hello')");
+        // Create .gitignore
+        fs.writeFileSync(path.join(repoDir, ".gitignore"), "node_modules/\ndist/\n*.log\n");
+        // Create gitignored files (should NOT be copied)
+        fs.mkdirSync(path.join(repoDir, "node_modules", "foo"), { recursive: true });
+        fs.writeFileSync(path.join(repoDir, "node_modules", "foo", "index.js"), "module.exports = {}");
+        fs.mkdirSync(path.join(repoDir, "dist"), { recursive: true });
+        fs.writeFileSync(path.join(repoDir, "dist", "bundle.js"), "bundled");
+        fs.writeFileSync(path.join(repoDir, "debug.log"), "log data");
+        // Commit everything that's tracked
+        execSync("git add .", { cwd: repoDir, stdio: "pipe" });
+        execSync('git commit -m "initial"', { cwd: repoDir, stdio: "pipe" });
+        // Create untracked-but-not-ignored file (should be copied)
+        fs.writeFileSync(path.join(repoDir, "newfile.txt"), "untracked but not ignored");
+    });
+    afterEach(() => {
+        fs.rmSync(repoDir, { recursive: true, force: true });
+        fs.rmSync(destDir, { recursive: true, force: true });
+    });
+    it("copies tracked files", async () => {
+        const { copyWorkspace } = await import("./cleanup.js");
+        copyWorkspace(repoDir, destDir);
+        expect(fs.existsSync(path.join(destDir, "README.md"))).toBe(true);
+        expect(fs.readFileSync(path.join(destDir, "README.md"), "utf-8")).toBe("# Hello");
+        expect(fs.existsSync(path.join(destDir, "src", "index.ts"))).toBe(true);
+        expect(fs.existsSync(path.join(destDir, ".gitignore"))).toBe(true);
+    });
+    it("copies untracked-but-not-ignored files", async () => {
+        const { copyWorkspace } = await import("./cleanup.js");
+        copyWorkspace(repoDir, destDir);
+        expect(fs.existsSync(path.join(destDir, "newfile.txt"))).toBe(true);
+        expect(fs.readFileSync(path.join(destDir, "newfile.txt"), "utf-8")).toBe("untracked but not ignored");
+    });
+    it("excludes gitignored files", async () => {
+        const { copyWorkspace } = await import("./cleanup.js");
+        copyWorkspace(repoDir, destDir);
+        expect(fs.existsSync(path.join(destDir, "node_modules"))).toBe(false);
+        expect(fs.existsSync(path.join(destDir, "dist"))).toBe(false);
+        expect(fs.existsSync(path.join(destDir, "debug.log"))).toBe(false);
+    });
+    it("preserves nested directory structure", async () => {
+        const { copyWorkspace } = await import("./cleanup.js");
+        copyWorkspace(repoDir, destDir);
+        expect(fs.readFileSync(path.join(destDir, "src", "index.ts"), "utf-8")).toBe("console.log('hello')");
+    });
+});
+// ── computeLockfileHash tests ─────────────────────────────────────────────────
+describe("computeLockfileHash", () => {
+    let repoDir;
+    beforeEach(() => {
+        repoDir = fs.mkdtempSync(path.join(os.tmpdir(), "oa-hash-test-"));
+        execSync("git init", { cwd: repoDir, stdio: "pipe" });
+        execSync('git config user.name "test"', { cwd: repoDir, stdio: "pipe" });
+        execSync('git config user.email "test@test.com"', { cwd: repoDir, stdio: "pipe" });
+    });
+    afterEach(() => {
+        fs.rmSync(repoDir, { recursive: true, force: true });
+    });
+    it("returns a hex string for a repo with a tracked lockfile", async () => {
+        const { computeLockfileHash } = await import("./cleanup.js");
+        fs.writeFileSync(path.join(repoDir, "pnpm-lock.yaml"), "lockfileVersion: '9.0'\n");
+        execSync("git add .", { cwd: repoDir, stdio: "pipe" });
+        execSync('git commit -m "init"', { cwd: repoDir, stdio: "pipe" });
+        const hash = computeLockfileHash(repoDir);
+        expect(hash).toMatch(/^[a-f0-9]{16}$/);
+    });
+    it("returns the same hash for the same lockfile content", async () => {
+        const { computeLockfileHash } = await import("./cleanup.js");
+        fs.writeFileSync(path.join(repoDir, "pnpm-lock.yaml"), "lockfileVersion: '9.0'\n");
+        execSync("git add .", { cwd: repoDir, stdio: "pipe" });
+        execSync('git commit -m "init"', { cwd: repoDir, stdio: "pipe" });
+        expect(computeLockfileHash(repoDir)).toBe(computeLockfileHash(repoDir));
+    });
+    it("returns a different hash when lockfile content changes", async () => {
+        const { computeLockfileHash } = await import("./cleanup.js");
+        fs.writeFileSync(path.join(repoDir, "pnpm-lock.yaml"), "lockfileVersion: '9.0'\n");
+        execSync("git add .", { cwd: repoDir, stdio: "pipe" });
+        execSync('git commit -m "init"', { cwd: repoDir, stdio: "pipe" });
+        const hash1 = computeLockfileHash(repoDir);
+        fs.writeFileSync(path.join(repoDir, "pnpm-lock.yaml"), "lockfileVersion: '9.0'\n# changed\n");
+        execSync("git add .", { cwd: repoDir, stdio: "pipe" });
+        execSync('git commit -m "update"', { cwd: repoDir, stdio: "pipe" });
+        const hash2 = computeLockfileHash(repoDir);
+        expect(hash1).not.toBe(hash2);
+    });
+    it("returns 'no-lockfile' when no lockfile exists", async () => {
+        const { computeLockfileHash } = await import("./cleanup.js");
+        // Empty repo, no lockfile
+        fs.writeFileSync(path.join(repoDir, "README.md"), "hi");
+        execSync("git add .", { cwd: repoDir, stdio: "pipe" });
+        execSync('git commit -m "init"', { cwd: repoDir, stdio: "pipe" });
+        expect(computeLockfileHash(repoDir)).toBe("no-lockfile");
+    });
+    it("detects package-lock.json (npm)", async () => {
+        const { computeLockfileHash } = await import("./cleanup.js");
+        fs.writeFileSync(path.join(repoDir, "package-lock.json"), '{"lockfileVersion": 3}');
+        execSync("git add .", { cwd: repoDir, stdio: "pipe" });
+        execSync('git commit -m "init"', { cwd: repoDir, stdio: "pipe" });
+        const hash = computeLockfileHash(repoDir);
+        expect(hash).toMatch(/^[a-f0-9]{16}$/);
+    });
+    it("detects yarn.lock", async () => {
+        const { computeLockfileHash } = await import("./cleanup.js");
+        fs.writeFileSync(path.join(repoDir, "yarn.lock"), "# yarn lockfile v1");
+        execSync("git add .", { cwd: repoDir, stdio: "pipe" });
+        execSync('git commit -m "init"', { cwd: repoDir, stdio: "pipe" });
+        const hash = computeLockfileHash(repoDir);
+        expect(hash).toMatch(/^[a-f0-9]{16}$/);
+    });
+    it("detects bun.lock", async () => {
+        const { computeLockfileHash } = await import("./cleanup.js");
+        fs.writeFileSync(path.join(repoDir, "bun.lock"), '{"lockfileVersion": 0}');
+        execSync("git add .", { cwd: repoDir, stdio: "pipe" });
+        execSync('git commit -m "init"', { cwd: repoDir, stdio: "pipe" });
+        const hash = computeLockfileHash(repoDir);
+        expect(hash).toMatch(/^[a-f0-9]{16}$/);
+    });
+});
+// ── isWarmNodeModules tests ───────────────────────────────────────────────────
+describe("isWarmNodeModules", () => {
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "oa-warm-test-"));
+    });
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it("returns false for a non-existent directory", async () => {
+        const { isWarmNodeModules } = await import("./cleanup.js");
+        expect(isWarmNodeModules(path.join(tmpDir, "does-not-exist"))).toBe(false);
+    });
+    it("returns false for an empty directory", async () => {
+        const { isWarmNodeModules } = await import("./cleanup.js");
+        const emptyDir = path.join(tmpDir, "empty");
+        fs.mkdirSync(emptyDir);
+        expect(isWarmNodeModules(emptyDir)).toBe(false);
+    });
+    it("returns false when directory has files but no .modules.yaml (corrupted)", async () => {
+        const { isWarmNodeModules } = await import("./cleanup.js");
+        const warmDir = path.join(tmpDir, "warm");
+        fs.mkdirSync(warmDir);
+        fs.writeFileSync(path.join(warmDir, "some-package"), "content");
+        expect(isWarmNodeModules(warmDir)).toBe(false);
+    });
+    it("returns true when directory has .modules.yaml (pnpm)", async () => {
+        const { isWarmNodeModules } = await import("./cleanup.js");
+        const warmDir = path.join(tmpDir, "warm");
+        fs.mkdirSync(warmDir);
+        fs.writeFileSync(path.join(warmDir, ".modules.yaml"), "hoistedDependencies: {}");
+        fs.mkdirSync(path.join(warmDir, ".pnpm"), { recursive: true });
+        expect(isWarmNodeModules(warmDir)).toBe(true);
+    });
+    it("returns true when directory has .package-lock.json (npm)", async () => {
+        const { isWarmNodeModules } = await import("./cleanup.js");
+        const warmDir = path.join(tmpDir, "warm-npm");
+        fs.mkdirSync(warmDir);
+        fs.writeFileSync(path.join(warmDir, ".package-lock.json"), "{}");
+        fs.writeFileSync(path.join(warmDir, "express"), "pkg");
+        expect(isWarmNodeModules(warmDir)).toBe(true);
+    });
+    it("returns true when directory has .yarn-integrity (yarn)", async () => {
+        const { isWarmNodeModules } = await import("./cleanup.js");
+        const warmDir = path.join(tmpDir, "warm-yarn");
+        fs.mkdirSync(warmDir);
+        fs.writeFileSync(path.join(warmDir, ".yarn-integrity"), "{}");
+        fs.writeFileSync(path.join(warmDir, "express"), "pkg");
+        expect(isWarmNodeModules(warmDir)).toBe(true);
+    });
+    it("returns true when directory has .cache (bun)", async () => {
+        const { isWarmNodeModules } = await import("./cleanup.js");
+        const warmDir = path.join(tmpDir, "warm-bun");
+        fs.mkdirSync(warmDir);
+        fs.mkdirSync(path.join(warmDir, ".cache"));
+        fs.writeFileSync(path.join(warmDir, "express"), "pkg");
+        expect(isWarmNodeModules(warmDir)).toBe(true);
+    });
+});
+// ── repairWarmCache tests ─────────────────────────────────────────────────────
+describe("repairWarmCache", () => {
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "oa-repair-test-"));
+    });
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it("returns 'cold' for a non-existent directory", async () => {
+        const { repairWarmCache } = await import("./cleanup.js");
+        expect(repairWarmCache(path.join(tmpDir, "nope"))).toBe("cold");
+    });
+    it("returns 'cold' for an empty directory", async () => {
+        const { repairWarmCache } = await import("./cleanup.js");
+        const emptyDir = path.join(tmpDir, "empty");
+        fs.mkdirSync(emptyDir);
+        expect(repairWarmCache(emptyDir)).toBe("cold");
+    });
+    it("returns 'warm' when .modules.yaml exists (pnpm)", async () => {
+        const { repairWarmCache } = await import("./cleanup.js");
+        const warmDir = path.join(tmpDir, "warm");
+        fs.mkdirSync(warmDir);
+        fs.writeFileSync(path.join(warmDir, ".modules.yaml"), "ok");
+        expect(repairWarmCache(warmDir)).toBe("warm");
+    });
+    it("returns 'warm' when .package-lock.json exists (npm)", async () => {
+        const { repairWarmCache } = await import("./cleanup.js");
+        const warmDir = path.join(tmpDir, "warm-npm");
+        fs.mkdirSync(warmDir);
+        fs.writeFileSync(path.join(warmDir, ".package-lock.json"), "{}");
+        expect(repairWarmCache(warmDir)).toBe("warm");
+    });
+    it("returns 'repaired' and nukes a corrupted cache (files but no sentinel)", async () => {
+        const { repairWarmCache } = await import("./cleanup.js");
+        const brokenDir = path.join(tmpDir, "broken");
+        fs.mkdirSync(path.join(brokenDir, ".pnpm", "yaml@2.8.2"), { recursive: true });
+        fs.writeFileSync(path.join(brokenDir, ".pnpm", "yaml@2.8.2", "Pair.js"), "broken");
+        expect(repairWarmCache(brokenDir)).toBe("repaired");
+        // Directory should be recreated empty
+        expect(fs.existsSync(brokenDir)).toBe(true);
+        expect(fs.readdirSync(brokenDir)).toHaveLength(0);
+    });
+});

package/dist/output/concurrency.js

@@ -0,0 +1,57 @@
+import os from "node:os";
+/**
+ * A simple Promise-based semaphore that limits how many async tasks
+ * execute concurrently. Used by the orchestrator to throttle parallel
+ * job launches within a dependency wave.
+ */
+export function createConcurrencyLimiter(max) {
+    let running = 0;
+    const queue = [];
+    function acquire() {
+        if (running < max) {
+            running++;
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            queue.push(() => {
+                running++;
+                resolve();
+            });
+        });
+    }
+    function release() {
+        running--;
+        const next = queue.shift();
+        if (next) {
+            next();
+        }
+    }
+    return {
+        /** Wrap an async function so it respects the concurrency limit. */
+        async run(fn) {
+            await acquire();
+            try {
+                return await fn();
+            }
+            finally {
+                release();
+            }
+        },
+        /** Current number of active tasks (for testing / logging). */
+        get active() {
+            return running;
+        },
+        /** Current queue depth (for testing / logging). */
+        get queued() {
+            return queue.length;
+        },
+    };
+}
+/**
+ * Determine the default max concurrent jobs based on the host CPU count.
+ * Returns floor(cpuCount / 2), with a minimum of 1.
+ */
+export function getDefaultMaxConcurrentJobs() {
+    const cpuCount = os.cpus().length;
+    return Math.max(1, Math.floor(cpuCount / 2));
+}

package/dist/output/concurrency.test.js

@@ -0,0 +1,88 @@
+import { describe, it, expect } from "vitest";
+import { createConcurrencyLimiter, getDefaultMaxConcurrentJobs } from "./concurrency.js";
+describe("createConcurrencyLimiter", () => {
+    it("limits concurrent execution to max", async () => {
+        const limiter = createConcurrencyLimiter(2);
+        let running = 0;
+        let maxRunning = 0;
+        const task = () => limiter.run(async () => {
+            running++;
+            maxRunning = Math.max(maxRunning, running);
+            // Simulate async work
+            await new Promise((r) => setTimeout(r, 50));
+            running--;
+        });
+        await Promise.all([task(), task(), task(), task(), task()]);
+        expect(maxRunning).toBe(2);
+    });
+    it("runs tasks serially when limit is 1", async () => {
+        const limiter = createConcurrencyLimiter(1);
+        const order = [];
+        const task = (id) => limiter.run(async () => {
+            order.push(id);
+            await new Promise((r) => setTimeout(r, 10));
+        });
+        await Promise.all([task(1), task(2), task(3)]);
+        expect(order).toEqual([1, 2, 3]);
+    });
+    it("runs all in parallel when limit exceeds task count", async () => {
+        const limiter = createConcurrencyLimiter(10);
+        let running = 0;
+        let maxRunning = 0;
+        const task = () => limiter.run(async () => {
+            running++;
+            maxRunning = Math.max(maxRunning, running);
+            await new Promise((r) => setTimeout(r, 50));
+            running--;
+        });
+        await Promise.all([task(), task(), task()]);
+        expect(maxRunning).toBe(3);
+    });
+    it("propagates errors without deadlocking", async () => {
+        const limiter = createConcurrencyLimiter(2);
+        const results = await Promise.allSettled([
+            limiter.run(async () => {
+                throw new Error("boom");
+            }),
+            limiter.run(async () => "ok"),
+            limiter.run(async () => "also ok"),
+        ]);
+        expect(results[0]).toMatchObject({ status: "rejected" });
+        expect(results[1]).toMatchObject({ status: "fulfilled", value: "ok" });
+        expect(results[2]).toMatchObject({ status: "fulfilled", value: "also ok" });
+    });
+    it("exposes active and queued counts", async () => {
+        const limiter = createConcurrencyLimiter(1);
+        let sawQueued = false;
+        const task1 = limiter.run(async () => {
+            // At this point task2 should be queued
+            await new Promise((r) => setTimeout(r, 50));
+        });
+        // Give task1 a moment to acquire
+        await new Promise((r) => setTimeout(r, 5));
+        const task2 = limiter.run(async () => {
+            // nothing
+        });
+        // After task1 acquired, check state
+        expect(limiter.active).toBe(1);
+        if (limiter.queued > 0) {
+            sawQueued = true;
+        }
+        await Promise.all([task1, task2]);
+        expect(sawQueued).toBe(true);
+        expect(limiter.active).toBe(0);
+        expect(limiter.queued).toBe(0);
+    });
+});
+describe("getDefaultMaxConcurrentJobs", () => {
+    it("returns at least 1", () => {
+        const result = getDefaultMaxConcurrentJobs();
+        expect(result).toBeGreaterThanOrEqual(1);
+    });
+    it("returns a reasonable number for the current host", () => {
+        const result = getDefaultMaxConcurrentJobs();
+        const os = require("os");
+        const expected = Math.max(1, Math.floor(os.cpus().length / 2));
+        expect(result).toBe(expected);
+    });
+});

package/dist/output/debug.js

@@ -0,0 +1,36 @@
+import { minimatch } from "minimatch";
+/**
+ * Lightweight debug logger with namespace support.
+ *
+ * Enable via DEBUG env var with glob patterns:
+ *   DEBUG=agent-ci:*        — all namespaces
+ *   DEBUG=agent-ci:cli      — CLI only
+ *   DEBUG=agent-ci:dtu      — DTU only
+ *   DEBUG=agent-ci:runner   — Runner only
+ *   DEBUG=agent-ci:cli,agent-ci:dtu — multiple
+ *
+ * Output goes to stderr so stdout stays clean for piping.
+ */
+const debugPatterns = (process.env.DEBUG || "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+function isEnabled(namespace) {
+    return debugPatterns.some((pattern) => minimatch(namespace, pattern));
+}
+export function createDebug(namespace) {
+    const enabled = isEnabled(namespace);
+    if (!enabled) {
+        return () => { };
+    }
+    const prefix = `  ${namespace}`;
+    return (...args) => {
+        const msg = args.map((a) => (typeof a === "string" ? a : JSON.stringify(a))).join(" ");
+        process.stderr.write(`${prefix} ${msg}\n`);
+    };
+}
+// Pre-configured loggers for each domain
+export const debugCli = createDebug("agent-ci:cli");
+export const debugRunner = createDebug("agent-ci:runner");
+export const debugDtu = createDebug("agent-ci:dtu");
+export const debugBoot = createDebug("agent-ci:boot");