@gethmy/agent 1.0.9 → 1.1.1

package/README.md

@@ -2,6 +2,8 @@
 
 Push-based agent daemon for [Harmony](https://gethmy.com). Watches board assignments via Supabase Realtime and autonomously implements and reviews cards using Claude CLI workers in isolated git worktrees.
 
+Built for **failsafe auto mode**: crashed daemons recover on restart, misconfigured columns fail fast, runaway costs trip a daily budget, and cards that can't pass build land in a dead-letter queue instead of bouncing forever.
+
 ## Prerequisites
 
 - [Node.js](https://nodejs.org) >= 20 or [Bun](https://bun.sh) >= 1.0
@@ -29,39 +31,88 @@ harmony-agent
 npx @gethmy/mcp setup
 ```
 
-2. Add agent config to `~/.harmony-mcp/config.json`:
+2. Add agent config to `~/.harmony-mcp/config.json`. Every field is optional — the snippet below shows the common options with their defaults. For the full schema (worktree, verification, completion, priority labels), see [docs/agent-daemon.md](../../docs/agent-daemon.md):
 
-```json
+```jsonc
 {
   "agent": {
     "poolSize": 1,
     "pickupColumns": ["To Do"],
-    "claude": {
-      "model": "sonnet"
-    },
+    "claude": { "model": "opus", "reviewModel": "sonnet" },
     "review": {
       "enabled": true,
       "pickupColumns": ["Review"],
       "moveToColumn": "Done",
       "failColumn": "To Do"
+    },
+    "budget": {
+      "maxAttemptsPerCard": 3,      // DLQ after N full failed runs
+      "maxCentsPerCard": 500,        // $5.00 per-card cost cap
+      "dailyBudgetCents": 5000,      // $50.00 total daily cap
+      "dlqLabel": "dlq"
+    },
+    "http": {
+      "enabled": true,
+      "port": 47821,
+      "bindAddr": "127.0.0.1"
+    },
+    "timing": {
+      "heartbeatMs": 30000,
+      "staleHeartbeatMs": 120000,
+      "reconcileIntervalMs": 60000,
+      "worktreeGcIntervalMs": 300000
     }
   }
 }
 ```
 
-## Usage
-
-Run from your git repository root:
+## CLI
 
 ```bash
-npx @gethmy/agent
+harmony-agent [run]              # Start the daemon (default)
+harmony-agent status             # Snapshot: workers, queues, DLQ, budget
+harmony-agent health             # Exit 0 if healthy, 1 otherwise
+harmony-agent doctor             # Preflight checks without starting the daemon
+harmony-agent gc                 # One-shot worktree garbage collection
+harmony-agent dlq list           # List dead-lettered cards
+harmony-agent dlq clear <cardId> # Release a card from the DLQ
+harmony-agent help               # Show usage
+
+# Flags:
+--pretty                         # Force colored human log output
+--json                           # Force JSON (one record per line)
+                                 # Default: pretty on a TTY, JSON when piped
 ```
 
-The daemon will:
+`status`, `health`, and `dlq clear` route through the running daemon's HTTP server (`127.0.0.1:47821` by default). `dlq clear` falls back to a direct state-store write only when the daemon is offline.
+
+## What the daemon does
+
+1. **Watches** the board in real time via Supabase Realtime.
+2. **Picks up** cards assigned to your agent user from configured columns.
+3. **Implements** changes in an isolated git worktree using a full-tool Claude run.
+4. **Verifies** the build + lint pass. Failures trigger an auto-fix attempt. Persistent failures move the card back to the `verification.failColumn` (default: `To Do`).
+5. **Pushes** the branch and moves the card to `Review`.
+6. **Reviews** the diff with a read-only Claude run against a live dev server. Verdict is either `approved` (PR created, `Ready to Merge` label) or `rejected` (findings posted, card moved back to pickup).
+
+## Guarantees
+
+- **Resumable.** A crash never orphans a card. On restart the daemon reconciles its own ghosts, returns implement cards to the pickup column with an `agent-recovered` label, ends their Harmony sessions, and cleans up worktrees.
+- **Trustworthy.** The review worker refuses to approve if the dev server didn't respond to an HTTP probe. Infrastructure failures are distinguished from code failures, so valid PRs don't get bounced back to rework.
+- **Bounded.** Per-card attempt and cost caps plus a daily budget cap prevent runaway spend. When caps hit, cards go to a dead-letter queue with a label instead of silently re-queuing.
+- **Observable.** Structured JSON logs on stderr (pipe to `jq`), a local HTTP status endpoint, and per-worker heartbeats so the reconciler can detect zombie runs within 2 minutes.
+- **Safe.** Claude subprocesses run in their own process group. Cancellation (SIGINT → SIGTERM → SIGKILL) terminates the whole subprocess tree, including build tools and dev servers Claude spawned.
+
+## State
+
+Durable state lives at `~/.harmony-mcp/agent-state.json`. Tracks live runs, per-card attempts and costs, daily spend, and DLQ markers. Atomic writes via write-to-tmp + rename.
+
+Worktrees live at `.harmony-worktrees/` inside your repo. A background sweep every 5 minutes removes directories older than 1 hour that no live run claims.
+
+## Debugging
+
+Every Claude CLI run writes a per-run log at `~/.harmony-mcp/runs/<runId>-card-<shortId>.log` — full stdout (NDJSON), stderr, parse errors, and an exit footer with tool-call and cost totals. Start there when a run ends silently or the card activity log shows only "Still working..." heartbeats.
+
+See [Debugging a Silent Run](../../docs/agent-daemon.md#debugging-a-silent-run) for interpretation table and retention notes.
 
-1. Watch for cards assigned to your agent user
-2. Pick up cards from configured columns
-3. Implement changes in isolated git worktrees
-4. Verify builds pass (build + lint)
-5. Push branches and move cards to Review
-6. Review cards and approve (create PR) or reject (move back to To Do)
+See [docs/agent-daemon.md](../../docs/agent-daemon.md) for the full architecture.

package/dist/__tests__/budget.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/budget.test.js

@@ -0,0 +1,94 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { BudgetGuard } from "../budget.js";
+import { StateStore } from "../state-store.js";
+import { DEFAULT_AGENT_CONFIG } from "../types.js";
+describe("BudgetGuard", () => {
+    let dir;
+    let store;
+    beforeEach(() => {
+        dir = mkdtempSync(join(tmpdir(), "budget-"));
+        store = new StateStore(join(dir, "state.json"));
+    });
+    afterEach(() => {
+        rmSync(dir, { recursive: true, force: true });
+    });
+    function makeGuard(overrides = {}) {
+        return new BudgetGuard({ ...DEFAULT_AGENT_CONFIG.budget, ...overrides }, store);
+    }
+    it("allows a fresh card with no history", () => {
+        const guard = makeGuard();
+        expect(guard.check("c1")).toEqual({ allow: true });
+    });
+    it("blocks a card already marked DLQ", async () => {
+        await store.markDlq("c1", "upstream test");
+        const guard = makeGuard();
+        const decision = guard.check("c1");
+        expect(decision).toMatchObject({ allow: false, reason: "dlq" });
+    });
+    it("blocks after attempts >= max", async () => {
+        await store.incrementAttempt("c1");
+        await store.incrementAttempt("c1");
+        await store.incrementAttempt("c1");
+        const guard = makeGuard({ maxAttemptsPerCard: 3 });
+        const decision = guard.check("c1");
+        expect(decision).toMatchObject({
+            allow: false,
+            reason: "max_attempts",
+        });
+    });
+    it("allows again after recordOutcome('success') resets attempts", async () => {
+        await store.incrementAttempt("c1");
+        await store.incrementAttempt("c1");
+        await store.recordOutcome("c1", "success");
+        const guard = makeGuard({ maxAttemptsPerCard: 2 });
+        expect(guard.check("c1")).toEqual({ allow: true });
+    });
+    it("blocks on per-card cost cap", async () => {
+        await store.addCost("c1", 600);
+        const guard = makeGuard({ maxCentsPerCard: 500 });
+        expect(guard.check("c1")).toMatchObject({
+            allow: false,
+            reason: "card_cost_cap",
+        });
+    });
+    it("blocks on daily budget exhaustion", async () => {
+        await store.addCost("c1", 5000);
+        const guard = makeGuard({ dailyBudgetCents: 5000 });
+        // Different card, but daily aggregate already at cap.
+        expect(guard.check("c2")).toMatchObject({
+            allow: false,
+            reason: "daily_budget",
+        });
+    });
+    it("treats DLQ, max_attempts, card_cost_cap as terminal (daily_budget is not)", () => {
+        const guard = makeGuard();
+        expect(guard.isTerminal("dlq")).toBe(true);
+        expect(guard.isTerminal("max_attempts")).toBe(true);
+        expect(guard.isTerminal("card_cost_cap")).toBe(true);
+        expect(guard.isTerminal("daily_budget")).toBe(false);
+    });
+    it("markDlq persists state + applies label via runTransition", async () => {
+        const guard = makeGuard();
+        const client = {
+            getBoard: vi.fn().mockResolvedValue({
+                columns: [{ id: "col-1", name: "To Do" }],
+                labels: [],
+            }),
+            createLabel: vi.fn().mockResolvedValue({ label: { id: "lbl-dlq" } }),
+            addLabelToCard: vi.fn().mockResolvedValue({}),
+        };
+        const card = {
+            id: "c1",
+            short_id: 99,
+            project_id: "p",
+            column_id: "col-1",
+            labelIds: [],
+        };
+        await guard.markDlq(client, card, "max_attempts", "3 attempts");
+        expect(store.isDlq("c1")).toBe(true);
+        expect(client.addLabelToCard).toHaveBeenCalledWith("c1", "lbl-dlq");
+    });
+});

package/dist/__tests__/config-validation.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/config-validation.test.js

@@ -0,0 +1,65 @@
+import { describe, expect, it, vi } from "vitest";
+import { ConfigValidationError, validateColumnReferences, } from "../config-validation.js";
+import { DEFAULT_AGENT_CONFIG } from "../types.js";
+function makeClient(columns) {
+    return {
+        getBoard: vi.fn().mockResolvedValue({
+            columns: columns.map((name, i) => ({ id: `col-${i}`, name })),
+            labels: [],
+        }),
+    };
+}
+describe("validateColumnReferences", () => {
+    it("passes when all configured columns exist (case-insensitive)", async () => {
+        const client = makeClient([
+            "to do",
+            "In Progress",
+            "REVIEW",
+            "Done",
+            "Needs Fix",
+        ]);
+        await expect(validateColumnReferences(client, "proj", DEFAULT_AGENT_CONFIG)).resolves.toBeUndefined();
+    });
+    it("throws a typed error listing every missing column", async () => {
+        const client = makeClient(["To Do", "Review", "Done"]);
+        const config = {
+            ...DEFAULT_AGENT_CONFIG,
+            verification: {
+                ...DEFAULT_AGENT_CONFIG.verification,
+                failColumn: "Needs Fix",
+            },
+        };
+        try {
+            await validateColumnReferences(client, "proj", config);
+            throw new Error("expected rejection");
+        }
+        catch (err) {
+            expect(err).toBeInstanceOf(ConfigValidationError);
+            const issues = err.issues;
+            expect(issues.some((i) => i.includes("Needs Fix"))).toBe(true);
+        }
+    });
+    it("skips review column checks when review is disabled", async () => {
+        const client = makeClient(["To Do", "Review", "Needs Fix"]);
+        const config = {
+            ...DEFAULT_AGENT_CONFIG,
+            completion: {
+                ...DEFAULT_AGENT_CONFIG.completion,
+                moveToColumn: "Review",
+            },
+            review: { ...DEFAULT_AGENT_CONFIG.review, enabled: false },
+        };
+        await expect(validateColumnReferences(client, "proj", config)).resolves.toBeUndefined();
+    });
+    it("reports the missing column along with the config path", async () => {
+        const client = makeClient(["To Do", "In Progress", "Review", "Done"]);
+        const config = {
+            ...DEFAULT_AGENT_CONFIG,
+            verification: {
+                ...DEFAULT_AGENT_CONFIG.verification,
+                failColumn: "DOES NOT EXIST",
+            },
+        };
+        await expect(validateColumnReferences(client, "proj", config)).rejects.toThrow(/verification\.failColumn: column "DOES NOT EXIST"/);
+    });
+});

package/dist/__tests__/dev-server-readiness.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/dev-server-readiness.test.js

@@ -0,0 +1,26 @@
+import { spawn } from "node:child_process";
+import { describe, expect, it } from "vitest";
+import { DevServerReadinessError, waitForDevServer } from "../verification.js";
+describe("waitForDevServer", () => {
+    it("resolves when readiness signal appears on stdout", async () => {
+        // node -e "console.log('server ready on localhost:4200'); setTimeout(()=>{}, 1000)"
+        const proc = spawn(process.execPath, [
+            "-e",
+            "console.log('server ready on localhost:4200'); setTimeout(() => {}, 1000);",
+        ], { stdio: ["ignore", "pipe", "pipe"] });
+        await expect(waitForDevServer(proc, 2000)).resolves.toBeUndefined();
+        proc.kill("SIGKILL");
+    });
+    it("rejects (does NOT resolve) on timeout", async () => {
+        // Silent child; no readiness signal.
+        const proc = spawn(process.execPath, ["-e", "setTimeout(() => {}, 5000);"], { stdio: ["ignore", "pipe", "pipe"] });
+        await expect(waitForDevServer(proc, 100)).rejects.toBeInstanceOf(DevServerReadinessError);
+        proc.kill("SIGKILL");
+    });
+    it("rejects if the process exits before becoming ready", async () => {
+        const proc = spawn(process.execPath, ["-e", "process.exit(7);"], {
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        await expect(waitForDevServer(proc, 5000)).rejects.toBeInstanceOf(DevServerReadinessError);
+    });
+});

package/dist/__tests__/http-server.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/http-server.test.js

@@ -0,0 +1,115 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { HttpServer, } from "../http-server.js";
+function baseStatus() {
+    return {
+        daemonId: "d-1",
+        daemonPid: 1234,
+        startedAt: Date.now(),
+        uptimeMs: 0,
+        workers: [],
+        implQueue: [],
+        reviewQueue: [],
+        dlq: [],
+        budget: { todayCents: 0, dailyCapCents: 5000 },
+    };
+}
+describe("HttpServer", () => {
+    let server;
+    let port;
+    let getHealth;
+    let handleCommand;
+    let clearDlq;
+    beforeEach(async () => {
+        // Ephemeral port via 0 doesn't round-trip through the options — use
+        // a random high port and retry on collision (rare in CI).
+        port = 40000 + Math.floor(Math.random() * 10000);
+        getHealth = () => ({ healthy: true, checks: { watcher: true } });
+        handleCommand = vi.fn().mockResolvedValue(undefined);
+        clearDlq = vi.fn().mockResolvedValue(undefined);
+        server = new HttpServer({
+            port,
+            bindAddr: "127.0.0.1",
+            getHealth: () => getHealth(),
+            getStatus: () => baseStatus(),
+            handleCommand: (c, id) => handleCommand(c, id),
+            clearDlq: (id) => clearDlq(id),
+        });
+        await server.start();
+    });
+    afterEach(async () => {
+        await server.stop();
+    });
+    async function get(path) {
+        return fetch(`http://127.0.0.1:${port}${path}`);
+    }
+    async function post(path) {
+        return fetch(`http://127.0.0.1:${port}${path}`, { method: "POST" });
+    }
+    it("GET /health returns 200 when healthy", async () => {
+        const res = await get("/health");
+        expect(res.status).toBe(200);
+        const body = await res.json();
+        expect(body.healthy).toBe(true);
+    });
+    it("GET /health returns 503 when unhealthy", async () => {
+        getHealth = () => ({
+            healthy: false,
+            checks: { watcher: false, reconciler: true },
+        });
+        const res = await get("/health");
+        expect(res.status).toBe(503);
+        const body = await res.json();
+        expect(body.checks.watcher).toBe(false);
+    });
+    it("GET /status returns the snapshot shape", async () => {
+        const res = await get("/status");
+        expect(res.status).toBe(200);
+        const body = await res.json();
+        expect(body).toHaveProperty("daemonId", "d-1");
+        expect(body).toHaveProperty("workers");
+        expect(body).toHaveProperty("implQueue");
+        expect(body).toHaveProperty("dlq");
+        expect(body).toHaveProperty("budget");
+    });
+    it("POST /pause/:cardId dispatches to handleCommand", async () => {
+        const res = await post("/pause/abc-123");
+        expect(res.status).toBe(200);
+        expect(handleCommand).toHaveBeenCalledWith("pause", "abc-123");
+    });
+    it("POST /resume/:cardId dispatches correctly", async () => {
+        const res = await post("/resume/xyz");
+        expect(res.status).toBe(200);
+        expect(handleCommand).toHaveBeenCalledWith("resume", "xyz");
+    });
+    it("POST /stop/:cardId dispatches correctly", async () => {
+        const res = await post("/stop/c1");
+        expect(res.status).toBe(200);
+        expect(handleCommand).toHaveBeenCalledWith("stop", "c1");
+    });
+    it("returns 404 for unknown paths", async () => {
+        const res = await get("/does-not-exist");
+        expect(res.status).toBe(404);
+    });
+    it("POST /dlq/clear/:cardId routes through the daemon", async () => {
+        const res = await post("/dlq/clear/card-42");
+        expect(res.status).toBe(200);
+        expect(clearDlq).toHaveBeenCalledWith("card-42");
+        const body = await res.json();
+        expect(body.ok).toBe(true);
+        expect(body.cardId).toBe("card-42");
+    });
+    it("POST /dlq/clear returns 500 with detail on failure", async () => {
+        clearDlq = vi.fn().mockRejectedValue(new Error("state store locked"));
+        const res = await post("/dlq/clear/card-99");
+        expect(res.status).toBe(500);
+        const body = await res.json();
+        expect(body.detail).toContain("state store locked");
+    });
+    it("returns 500 with detail when handleCommand throws", async () => {
+        handleCommand = vi.fn().mockRejectedValue(new Error("worker gone"));
+        const res = await post("/stop/c1");
+        expect(res.status).toBe(500);
+        const body = await res.json();
+        expect(body.detail).toContain("worker gone");
+    });
+});

package/dist/__tests__/log.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/log.test.js

@@ -0,0 +1,115 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+describe("log", () => {
+    let writes;
+    let origWrite;
+    let origArgv;
+    beforeEach(() => {
+        writes = [];
+        origWrite = process.stderr.write;
+        origArgv = process.argv;
+        process.stderr.write = ((chunk) => {
+            writes.push(chunk);
+            return true;
+        });
+        delete process.env.HARMONY_AGENT_PRETTY;
+        delete process.env.HARMONY_AGENT_JSON;
+        delete process.env.DEBUG;
+        vi.resetModules();
+    });
+    afterEach(() => {
+        process.stderr.write = origWrite;
+        process.argv = origArgv;
+    });
+    it("emits JSON lines when stderr is not a TTY", async () => {
+        // Vitest stderr is not a TTY by default; no need to force.
+        const { log } = await import("../log.js");
+        log.info("worker", "hello", { cardId: "c1", runId: "r1" });
+        const parsed = JSON.parse(writes[0]);
+        expect(parsed).toMatchObject({
+            level: "info",
+            tag: "worker",
+            msg: "hello",
+            cardId: "c1",
+            runId: "r1",
+        });
+        expect(parsed.ts).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+    });
+    it("emits pretty output when stderr is a TTY", async () => {
+        const originalIsTTY = process.stderr.isTTY;
+        Object.defineProperty(process.stderr, "isTTY", {
+            value: true,
+            configurable: true,
+        });
+        try {
+            const { log } = await import("../log.js");
+            log.info("daemon", "up");
+            expect(() => JSON.parse(writes[0])).toThrow();
+            expect(writes[0]).toContain("INFO");
+            expect(writes[0]).toContain("[daemon]");
+        }
+        finally {
+            Object.defineProperty(process.stderr, "isTTY", {
+                value: originalIsTTY,
+                configurable: true,
+            });
+        }
+    });
+    it("--json forces JSON even on a TTY", async () => {
+        const originalIsTTY = process.stderr.isTTY;
+        Object.defineProperty(process.stderr, "isTTY", {
+            value: true,
+            configurable: true,
+        });
+        process.argv = [...process.argv, "--json"];
+        try {
+            const { log } = await import("../log.js");
+            log.info("daemon", "up");
+            const parsed = JSON.parse(writes[0]);
+            expect(parsed.msg).toBe("up");
+        }
+        finally {
+            Object.defineProperty(process.stderr, "isTTY", {
+                value: originalIsTTY,
+                configurable: true,
+            });
+        }
+    });
+    it("HARMONY_AGENT_JSON=1 beats HARMONY_AGENT_PRETTY=1", async () => {
+        process.env.HARMONY_AGENT_PRETTY = "1";
+        process.env.HARMONY_AGENT_JSON = "1";
+        const { log } = await import("../log.js");
+        log.info("daemon", "hi");
+        const parsed = JSON.parse(writes[0]);
+        expect(parsed.msg).toBe("hi");
+    });
+    it("suppresses debug when DEBUG is unset", async () => {
+        const { log } = await import("../log.js");
+        log.debug("x", "quiet");
+        expect(writes).toEqual([]);
+    });
+    it("emits debug when DEBUG is set", async () => {
+        process.env.DEBUG = "1";
+        const { log } = await import("../log.js");
+        log.debug("x", "loud");
+        expect(writes).toHaveLength(1);
+        const parsed = JSON.parse(writes[0]);
+        expect(parsed.level).toBe("debug");
+    });
+    it("log.event attaches the event field", async () => {
+        const { log } = await import("../log.js");
+        log.event("pool", "card_enqueued", { cardId: "c2" });
+        const parsed = JSON.parse(writes[0]);
+        expect(parsed.event).toBe("card_enqueued");
+        expect(parsed.msg).toBe("card_enqueued");
+        expect(parsed.cardId).toBe("c2");
+    });
+    it("switches to ANSI pretty output under HARMONY_AGENT_PRETTY=1", async () => {
+        process.env.HARMONY_AGENT_PRETTY = "1";
+        const { log } = await import("../log.js");
+        log.warn("daemon", "heads up");
+        // Pretty output is not JSON — should fail parse and contain WARN label
+        expect(() => JSON.parse(writes[0])).toThrow();
+        expect(writes[0]).toContain("WARN");
+        expect(writes[0]).toContain("[daemon]");
+    });
+});

package/dist/__tests__/process-group.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/process-group.test.js

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest";
+import { signalGroup, spawnInGroup, terminateGroup } from "../process-group.js";
+describe("process-group", () => {
+    it("places the child in its own process group (pid === pgid)", async () => {
+        if (process.platform === "win32")
+            return;
+        const proc = spawnInGroup("sh", ["-c", "ps -o pgid= -p $$ | tr -d ' '"]);
+        let stdout = "";
+        proc.stdout?.on("data", (d) => {
+            stdout += d.toString();
+        });
+        await new Promise((resolve) => {
+            proc.on("exit", () => resolve());
+        });
+        const pgid = parseInt(stdout.trim(), 10);
+        expect(pgid).toBe(proc.pid);
+    });
+    it("signalGroup handles already-dead processes silently", () => {
+        const fakeProc = {
+            pid: 999_999_999,
+            killed: false,
+            kill: () => true,
+        };
+        expect(() => signalGroup(fakeProc, "SIGTERM")).not.toThrow();
+    });
+    it("terminateGroup exits a cooperative child on SIGINT", async () => {
+        if (process.platform === "win32")
+            return;
+        const proc = spawnInGroup(process.execPath, [
+            "-e",
+            "process.on('SIGINT', () => process.exit(0)); setInterval(()=>{}, 1000);",
+        ]);
+        // Capture the exit state up front so we never miss it.
+        const exited = new Promise((resolve) => {
+            proc.once("exit", (code, signal) => resolve({ code, signal }));
+        });
+        // Give the child enough time to attach its SIGINT handler even
+        // under contention (9 parallel test files, git spawning, etc.).
+        await new Promise((r) => setTimeout(r, 500));
+        await terminateGroup(proc, {
+            sigintTimeoutMs: 2000,
+            sigtermTimeoutMs: 500,
+        });
+        const result = await exited;
+        // Either the handler fired (code=0) or we escalated past it — in
+        // both cases the termination contract is kept. We really only want
+        // to prove the process group was reached.
+        expect(result.code !== null || result.signal !== null).toBe(true);
+    });
+    it("terminateGroup escalates to SIGKILL when the group ignores signals", async () => {
+        if (process.platform === "win32")
+            return;
+        const proc = spawnInGroup(process.execPath, [
+            "-e",
+            "process.on('SIGINT', () => {}); process.on('SIGTERM', () => {}); setInterval(()=>{}, 1000);",
+        ]);
+        const exited = new Promise((resolve) => {
+            proc.once("exit", (code, signal) => resolve({ code, signal }));
+        });
+        await new Promise((r) => setTimeout(r, 150));
+        await terminateGroup(proc, {
+            sigintTimeoutMs: 200,
+            sigtermTimeoutMs: 200,
+        });
+        const result = await exited;
+        expect(result.signal === "SIGKILL" || result.code !== null).toBe(true);
+    });
+});

package/dist/__tests__/reconcile-heartbeat.test.d.ts

@@ -0,0 +1 @@
+export {};