immortal-js 1.0.0

package/packages/core/test/retry.test.ts

@@ -0,0 +1,110 @@
+/**
+ * @file retry.test.ts
+ * @description Comprehensive tests for RetryEngine
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// ── Mocked dependencies ────────────────────────────────────────────────────
+vi.mock("../src/event-bus.js", () => ({
+  getEventBus: () => ({ emit: vi.fn() }),
+}));
+
+vi.mock("../src/logger.js", () => ({
+  getLogger: () => ({ debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() }),
+}));
+
+vi.mock("../src/safe-zone/AsyncBoundary.js", () => ({
+  AsyncBoundary: { getRequestId: () => "test-request-123" },
+}));
+
+// Import after mocks
+const { RetryEngine, withRetry, calculateBackoff } = await import("../src/recovery/RetryEngine.js");
+const { RetryExhaustedError } = await import("../src/types.js");
+
+describe("RetryEngine", () => {
+  beforeEach(() => {
+    RetryEngine.resetBudget();
+    vi.useFakeTimers();
+  });
+
+  it("should succeed on first attempt without retrying", async () => {
+    vi.useRealTimers();
+    const engine = new RetryEngine({ maxAttempts: 3 });
+    const fn = vi.fn().mockResolvedValue("success");
+
+    const result = await engine.execute(fn, "test-op");
+
+    expect(result).toBe("success");
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("should retry transient failures and succeed", async () => {
+    vi.useRealTimers();
+    const engine = new RetryEngine({
+      maxAttempts: 3,
+      baseDelayMs: 1,
+      maxDelayMs: 10,
+    });
+
+    let callCount = 0;
+    const fn = vi.fn().mockImplementation(async () => {
+      callCount++;
+      if (callCount < 3) {
+        const err = new Error("ECONNRESET");
+        (err as NodeJS.ErrnoException).code = "ECONNRESET";
+        throw err;
+      }
+      return "recovered";
+    });
+
+    const result = await engine.execute(fn, "retry-test");
+
+    expect(result).toBe("recovered");
+    expect(fn).toHaveBeenCalledTimes(3);
+  });
+
+  it("should throw RetryExhaustedError after maxAttempts", async () => {
+    vi.useRealTimers();
+    const engine = new RetryEngine({
+      maxAttempts: 2,
+      baseDelayMs: 1,
+      maxDelayMs: 5,
+    });
+
+    const err = new Error("ECONNRESET");
+    (err as NodeJS.ErrnoException).code = "ECONNRESET";
+    const fn = vi.fn().mockRejectedValue(err);
+
+    await expect(engine.execute(fn, "exhaust-test")).rejects.toBeInstanceOf(RetryExhaustedError);
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it("should NOT retry non-retryable errors (e.g. 400 Bad Request)", async () => {
+    vi.useRealTimers();
+    const engine = new RetryEngine({ maxAttempts: 5, baseDelayMs: 1 });
+
+    const err = new Error("Bad Request");
+    (err as Error & { statusCode: number }).statusCode = 400;
+    const fn = vi.fn().mockRejectedValue(err);
+
+    await expect(engine.execute(fn)).rejects.toThrow("Bad Request");
+    // Should only have been called once (no retries for 400)
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("calculateBackoff should return value within expected range", () => {
+    const delay = calculateBackoff(1, 200, 10000, 0.3);
+    expect(delay).toBeGreaterThan(0);
+    expect(delay).toBeLessThanOrEqual(10000);
+  });
+
+  it("withRetry functional API should work", async () => {
+    vi.useRealTimers();
+    const result = await withRetry(
+      async () => "functional-result",
+      { maxAttempts: 3, baseDelayMs: 1 }
+    );
+    expect(result).toBe("functional-result");
+  });
+});

package/packages/core/test/safe-zone.test.ts

@@ -0,0 +1,271 @@
+/**
+ * @file safe-zone.test.ts
+ * @description Tests for the Safe Zone layer.
+ *
+ * Actual API shapes (from source):
+ *   AsyncBoundary — all methods are static:
+ *     AsyncBoundary.run(ctx, fn)
+ *     AsyncBoundary.getContext()
+ *     AsyncBoundary.getRequestId()
+ *     AsyncBoundary.enrich(partial)
+ *
+ *   classifyError(err) → "operational" | "programming" | "unknown"
+ *   serializeError(err) → SerializedError
+ *
+ * NOTE: classifyError classifies generic Error as "operational" (conservative).
+ * Only TypeError/RangeError/SyntaxError/ReferenceError etc. are "programming".
+ */
+
+import { describe, it, expect } from "vitest";
+import {
+  AsyncBoundary,
+  asyncBoundary,
+  getRequestContext,
+  getRequestId,
+} from "../src/safe-zone/AsyncBoundary.js";
+import {
+  classifyError,
+  serializeError,
+} from "../src/safe-zone/ErrorTrap.js";
+import type { RequestContext } from "../src/types.js";
+
+// ─── helpers ─────────────────────────────────────────────────────────────────
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+function makeCtx(id = "test-req"): RequestContext {
+  return { requestId: id, startedAt: Date.now() };
+}
+
+// ─── AsyncBoundary — static API ───────────────────────────────────────────────
+
+describe("AsyncBoundary.run — context propagation", () => {
+  it("returns undefined context outside run()", () => {
+    // After all prior tests complete, we should be outside any boundary
+    const ctx = AsyncBoundary.getContext();
+    // May or may not be defined depending on test isolation — just don't throw
+    expect(ctx === undefined || typeof ctx === "object").toBe(true);
+  });
+
+  it("provides context inside run()", async () => {
+    await AsyncBoundary.run(makeCtx("ctx-001"), async () => {
+      const ctx = AsyncBoundary.getContext();
+      expect(ctx).toBeDefined();
+      expect(ctx?.requestId).toBe("ctx-001");
+    });
+  });
+
+  it("propagates context across awaited async operations", async () => {
+    await AsyncBoundary.run(makeCtx("propagation-test"), async () => {
+      await Promise.resolve();
+      await new Promise<void>((r) => setTimeout(r, 10));
+      const ctx = AsyncBoundary.getContext();
+      expect(ctx?.requestId).toBe("propagation-test");
+    });
+  });
+
+  it("isolates contexts between concurrent run() calls", async () => {
+    const results: string[] = [];
+
+    await Promise.all([
+      AsyncBoundary.run(makeCtx("ctx-A"), async () => {
+        await sleep(20);
+        results.push(AsyncBoundary.getContext()?.requestId ?? "missing");
+      }),
+      AsyncBoundary.run(makeCtx("ctx-B"), async () => {
+        await sleep(5);
+        results.push(AsyncBoundary.getContext()?.requestId ?? "missing");
+      }),
+    ]);
+
+    expect(results).toContain("ctx-A");
+    expect(results).toContain("ctx-B");
+    expect(results).toHaveLength(2);
+  });
+
+  it("enrich() adds fields to the active context", async () => {
+    await AsyncBoundary.run(makeCtx("enrich-test"), async () => {
+      AsyncBoundary.enrich({ custom: { userId: "user-42" } });
+      const ctx = AsyncBoundary.getContext();
+      expect(ctx?.custom?.["userId"]).toBe("user-42");
+      expect(ctx?.requestId).toBe("enrich-test");
+    });
+  });
+
+  it("getRequestId() returns requestId when inside run()", async () => {
+    await AsyncBoundary.run(makeCtx("known-id"), async () => {
+      const id = AsyncBoundary.getRequestId();
+      expect(id).toBe("known-id");
+    });
+  });
+
+  it("getRequestId() returns undefined when outside run()", () => {
+    // Relies on the fact that we're between async boundaries here
+    // This just verifies it doesn't throw
+    expect(() => AsyncBoundary.getRequestId()).not.toThrow();
+  });
+
+  it("passes return value from run()", async () => {
+    const result = await AsyncBoundary.run(makeCtx("ret"), async () => 42);
+    expect(result).toBe(42);
+  });
+});
+
+// ─── Convenience exports ──────────────────────────────────────────────────────
+
+describe("getRequestContext / getRequestId convenience functions", () => {
+  it("getRequestContext returns same as AsyncBoundary.getContext() inside run()", async () => {
+    await AsyncBoundary.run(makeCtx("convenience-test"), async () => {
+      const ctx = getRequestContext();
+      expect(ctx?.requestId).toBe("convenience-test");
+    });
+  });
+
+  it("getRequestId returns 'unknown' when outside any context", () => {
+    const id = getRequestId();
+    expect(typeof id).toBe("string");
+    // May be "unknown" or the actual requestId if a parent run() is active
+    expect(id.length).toBeGreaterThan(0);
+  });
+});
+
+// ─── asyncBoundary HOF ────────────────────────────────────────────────────────
+
+describe("asyncBoundary HOF wrapper", () => {
+  it("executes the wrapped function inside a fresh context", async () => {
+    let capturedId: string | undefined;
+
+    const wrapped = asyncBoundary(async (..._args: unknown[]) => {
+      capturedId = AsyncBoundary.getContext()?.requestId;
+    });
+
+    await wrapped();
+    expect(typeof capturedId).toBe("string");
+    expect(capturedId).not.toBe(""); // auto-generated UUID
+  });
+
+  it("passes through the return value", async () => {
+    const wrapped = asyncBoundary(async () => 99 as unknown);
+    const result = await wrapped();
+    expect(result).toBe(99);
+  });
+
+  it("passes arguments through to the wrapped function", async () => {
+    let received: number[] = [];
+    const wrapped = asyncBoundary(async (a: unknown, b: unknown) => {
+      received = [a as number, b as number];
+    });
+    await wrapped(3, 7);
+    expect(received).toEqual([3, 7]);
+  });
+});
+
+// ─── classifyError ────────────────────────────────────────────────────────────
+
+describe("classifyError", () => {
+  it("classifies TypeError as programming", () => {
+    expect(classifyError(new TypeError("bad type"))).toBe("programming");
+  });
+
+  it("classifies ReferenceError as programming", () => {
+    expect(classifyError(new ReferenceError("not defined"))).toBe("programming");
+  });
+
+  it("classifies SyntaxError as programming", () => {
+    expect(classifyError(new SyntaxError("unexpected token"))).toBe("programming");
+  });
+
+  it("classifies RangeError as programming", () => {
+    expect(classifyError(new RangeError("out of range"))).toBe("programming");
+  });
+
+  it("classifies ECONNREFUSED as operational", () => {
+    const err = new Error("connection refused");
+    (err as NodeJS.ErrnoException).code = "ECONNREFUSED";
+    expect(classifyError(err)).toBe("operational");
+  });
+
+  it("classifies ETIMEDOUT as operational", () => {
+    const err = new Error("timeout");
+    (err as NodeJS.ErrnoException).code = "ETIMEDOUT";
+    expect(classifyError(err)).toBe("operational");
+  });
+
+  it("classifies ENOTFOUND as operational", () => {
+    const err = new Error("ENOTFOUND");
+    (err as NodeJS.ErrnoException).code = "ENOTFOUND";
+    expect(classifyError(err)).toBe("operational");
+  });
+
+  it("classifies errors with isOperational=true as operational", () => {
+    const err = Object.assign(new Error("custom"), { isOperational: true });
+    expect(classifyError(err)).toBe("operational");
+  });
+
+  it("classifies errors with isOperational=false as programming", () => {
+    const err = Object.assign(new Error("custom"), { isOperational: false });
+    expect(classifyError(err)).toBe("programming");
+  });
+
+  it("classifies 4xx HTTP errors as operational", () => {
+    const err = Object.assign(new Error("not found"), { statusCode: 404 });
+    expect(classifyError(err)).toBe("operational");
+  });
+
+  it("classifies generic Error() conservatively as operational", () => {
+    // Immortal classifies unknowns as operational to avoid unnecessary restarts
+    expect(classifyError(new Error("some message"))).toBe("operational");
+  });
+
+  it("classifies non-Error throws as unknown", () => {
+    expect(classifyError("just a string")).toBe("unknown");
+    expect(classifyError(42)).toBe("unknown");
+    expect(classifyError(null)).toBe("unknown");
+  });
+});
+
+// ─── serializeError ──────────────────────────────────────────────────────────
+
+describe("serializeError", () => {
+  it("serializes a standard Error correctly", () => {
+    const err = new Error("test message");
+    const s = serializeError(err);
+    expect(s.name).toBe("Error");
+    expect(s.message).toBe("test message");
+  });
+
+  it("includes name from Error subclasses", () => {
+    class PaymentError extends Error {
+      constructor(msg: string) { super(msg); this.name = "PaymentError"; }
+    }
+    const s = serializeError(new PaymentError("declined"));
+    expect(s.name).toBe("PaymentError");
+    expect(s.message).toBe("declined");
+  });
+
+  it("serializes raw string throws", () => {
+    const s = serializeError("raw string");
+    expect(s.name).toBe("Error");
+    expect(s.message).toBe("raw string");
+  });
+
+  it("serializes null without throwing", () => {
+    const s = serializeError(null);
+    expect(s.name).toBe("UnknownError");
+  });
+
+  it("serializes plain object without throwing", () => {
+    const s = serializeError({ code: 500, msg: "oops" });
+    expect(s.name).toBe("UnknownError");
+    expect(typeof s.message).toBe("string");
+  });
+
+  it("includes code and statusCode if present", () => {
+    const err = Object.assign(new Error("bad"), { code: "ERR_X", statusCode: 503 });
+    const s = serializeError(err);
+    expect(s.code).toBe("ERR_X");
+    expect(s.statusCode).toBe(503);
+  });
+});

package/packages/core/test/supervisor.test.ts

@@ -0,0 +1,310 @@
+/**
+ * @file supervisor.test.ts
+ * @description Tests for the Supervisor and RestartStrategy layers.
+ *
+ * Actual API shapes (from source):
+ *   - computeRestartDecision(failedId, allWorkers: WorkerEntry[], strategy)
+ *     → { workersToRestart: string[], strategy }
+ *   - new Supervisor(options?: { config?, onEscalation? })
+ *   - supervisor.register(id, spawnFn)  ← spawnFn returns { terminate? }
+ *   - supervisor.onWorkerExit(id, exitCode?)
+ *   - supervisor.stop(id)  — async
+ *   - supervisor.stopAll() — async
+ *   - supervisor.getWorkerStatuses() → WorkerStatus[]
+ *   - supervisor.updateWorkerMetrics(id, { memoryMb?, cpuPercent?, pid? })
+ *   - supervisor.requestGracefulRestart(id, reason?)
+ */
+
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { Supervisor } from "../src/supervision/Supervisor.js";
+import { computeRestartDecision } from "../src/supervision/RestartStrategy.js";
+import type { WorkerEntry } from "../src/supervision/RestartStrategy.js";
+
+// ─── helpers ─────────────────────────────────────────────────────────────────
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+/** A spawnFn that always returns a simple terminatable object */
+function makeSpawn() {
+  const terminated: boolean[] = [];
+  const fn = vi.fn(() => ({
+    terminate: () => {
+      terminated.push(true);
+    },
+  }));
+  return { fn, terminated };
+}
+
+// ─── computeRestartDecision — pure function ───────────────────────────────────
+
+describe("computeRestartDecision — one_for_one", () => {
+  const workers: WorkerEntry[] = [
+    { id: "w1", index: 0, restart: vi.fn() },
+    { id: "w2", index: 1, restart: vi.fn() },
+    { id: "w3", index: 2, restart: vi.fn() },
+  ];
+
+  it("should restart only the failed worker", () => {
+    const d = computeRestartDecision("w2", workers, "one_for_one");
+    expect(d.workersToRestart).toEqual(["w2"]);
+    expect(d.strategy).toBe("one_for_one");
+  });
+
+  it("should return empty list for unknown worker", () => {
+    const d = computeRestartDecision("w-unknown", workers, "one_for_one");
+    expect(d.workersToRestart).toHaveLength(0);
+  });
+});
+
+describe("computeRestartDecision — one_for_all", () => {
+  const workers: WorkerEntry[] = [
+    { id: "w1", index: 0, restart: vi.fn() },
+    { id: "w2", index: 1, restart: vi.fn() },
+    { id: "w3", index: 2, restart: vi.fn() },
+  ];
+
+  it("should restart ALL workers when any one fails", () => {
+    const d = computeRestartDecision("w1", workers, "one_for_all");
+    expect(d.workersToRestart.sort()).toEqual(["w1", "w2", "w3"]);
+  });
+});
+
+describe("computeRestartDecision — rest_for_one", () => {
+  const workers: WorkerEntry[] = [
+    { id: "w1", index: 0, restart: vi.fn() },
+    { id: "w2", index: 1, restart: vi.fn() },
+    { id: "w3", index: 2, restart: vi.fn() },
+    { id: "w4", index: 3, restart: vi.fn() },
+  ];
+
+  it("should restart failed + all subsequent workers", () => {
+    const d = computeRestartDecision("w2", workers, "rest_for_one");
+    expect(d.workersToRestart).toContain("w2");
+    expect(d.workersToRestart).toContain("w3");
+    expect(d.workersToRestart).toContain("w4");
+    expect(d.workersToRestart).not.toContain("w1");
+  });
+
+  it("should restart only the tail when last worker fails", () => {
+    const d = computeRestartDecision("w4", workers, "rest_for_one");
+    expect(d.workersToRestart).toEqual(["w4"]);
+  });
+
+  it("should restart all when the first worker fails", () => {
+    const d = computeRestartDecision("w1", workers, "rest_for_one");
+    expect(d.workersToRestart.sort()).toEqual(["w1", "w2", "w3", "w4"]);
+  });
+});
+
+// ─── Supervisor — registration ────────────────────────────────────────────────
+
+describe("Supervisor — register", () => {
+  it("should register a worker and call spawnFn once", async () => {
+    const { fn } = makeSpawn();
+    const sup = new Supervisor();
+    sup.register("api", fn);
+    expect(fn).toHaveBeenCalledTimes(1);
+    await sup.stopAll();
+  });
+
+  it("should throw if the same id is registered twice", async () => {
+    const { fn } = makeSpawn();
+    const sup = new Supervisor();
+    sup.register("dup", fn);
+    expect(() => sup.register("dup", fn)).toThrow(/already registered/i);
+    await sup.stopAll();
+  });
+
+  it("should reflect registered worker in getWorkerStatuses()", async () => {
+    const { fn } = makeSpawn();
+    const sup = new Supervisor();
+    sup.register("worker-1", fn);
+    const statuses = sup.getWorkerStatuses();
+    expect(statuses).toHaveLength(1);
+    expect(statuses[0]!.id).toBe("worker-1");
+    expect(statuses[0]!.state).toBe("running");
+    await sup.stopAll();
+  });
+});
+
+// ─── Supervisor — restart on exit ────────────────────────────────────────────
+
+describe("Supervisor — onWorkerExit triggers restart", () => {
+  it("should call spawnFn again after a crash", async () => {
+    const { fn } = makeSpawn();
+    const sup = new Supervisor({
+      config: { strategy: "one_for_one", baseRestartDelayMs: 10 },
+    });
+    sup.register("crash-worker", fn);
+    expect(fn).toHaveBeenCalledTimes(1);
+
+    sup.onWorkerExit("crash-worker", 1);
+    await sleep(60);
+
+    expect(fn).toHaveBeenCalledTimes(2); // restarted once
+    await sup.stopAll();
+  });
+
+  it("should respect baseRestartDelayMs before restarting", async () => {
+    const { fn } = makeSpawn();
+    const sup = new Supervisor({
+      config: { strategy: "one_for_one", baseRestartDelayMs: 150 },
+    });
+    sup.register("slow-restart", fn);
+    sup.onWorkerExit("slow-restart", 1);
+
+    await sleep(30); // not yet
+    expect(fn).toHaveBeenCalledTimes(1); // only initial spawn
+
+    await sleep(200); // now past delay
+    expect(fn).toHaveBeenCalledTimes(2);
+    await sup.stopAll();
+  });
+
+  it("should ignore exits for unknown worker ids", async () => {
+    const sup = new Supervisor();
+    expect(() => sup.onWorkerExit("ghost", 1)).not.toThrow();
+    await sup.stopAll();
+  });
+});
+
+// ─── Supervisor — escalation ceiling ─────────────────────────────────────────
+
+describe("Supervisor — escalation ceiling", () => {
+  it("should call onEscalation after maxRestartsInWindow crashes", async () => {
+    const onEscalation = vi.fn();
+    const { fn } = makeSpawn();
+
+    const sup = new Supervisor({
+      config: {
+        strategy: "one_for_one",
+        maxRestartsInWindow: 3,
+        windowMs: 10_000,
+        baseRestartDelayMs: 5,
+      },
+      onEscalation,
+    });
+    sup.register("crasher", fn);
+
+    // Trigger 4 exits — 3 allowed, 4th escalates
+    sup.onWorkerExit("crasher", 1); await sleep(20);
+    sup.onWorkerExit("crasher", 1); await sleep(20);
+    sup.onWorkerExit("crasher", 1); await sleep(20);
+    sup.onWorkerExit("crasher", 1); await sleep(20);
+
+    expect(onEscalation).toHaveBeenCalledTimes(1);
+    const [calledId] = onEscalation.mock.calls[0] as [string];
+    expect(calledId).toBe("crasher");
+    await sup.stopAll();
+  });
+
+  it("should set worker status to escalated and stop restarting", async () => {
+    const onEscalation = vi.fn();
+    const { fn } = makeSpawn();
+
+    const sup = new Supervisor({
+      config: {
+        strategy: "one_for_one",
+        maxRestartsInWindow: 2,
+        windowMs: 10_000,
+        baseRestartDelayMs: 5,
+      },
+      onEscalation,
+    });
+    sup.register("looper", fn);
+
+    // Crash 3 times (limit = 2, so 3rd is escalation)
+    sup.onWorkerExit("looper", 1); await sleep(20);
+    sup.onWorkerExit("looper", 1); await sleep(20);
+    sup.onWorkerExit("looper", 1); await sleep(20);
+
+    const statuses = sup.getWorkerStatuses();
+    const w = statuses.find((s) => s.id === "looper");
+    expect(w?.state).toBe("escalated");
+    await sup.stopAll();
+  });
+});
+
+// ─── Supervisor — metrics update ─────────────────────────────────────────────
+
+describe("Supervisor — updateWorkerMetrics", () => {
+  it("should store metrics for a registered worker", async () => {
+    const { fn } = makeSpawn();
+    const sup = new Supervisor();
+    sup.register("metrics-w", fn);
+
+    sup.updateWorkerMetrics("metrics-w", { memoryMb: 120, cpuPercent: 45 });
+
+    const statuses = sup.getWorkerStatuses();
+    const w = statuses.find((s) => s.id === "metrics-w")!;
+    expect(w.memoryMb).toBe(120);
+    expect(w.cpuPercent).toBe(45);
+    await sup.stopAll();
+  });
+
+  it("should silently ignore unknown worker ids", async () => {
+    const sup = new Supervisor();
+    expect(() =>
+      sup.updateWorkerMetrics("ghost", { memoryMb: 50, cpuPercent: 10 })
+    ).not.toThrow();
+    await sup.stopAll();
+  });
+});
+
+// ─── Supervisor — requestGracefulRestart ──────────────────────────────────────
+
+describe("Supervisor — requestGracefulRestart", () => {
+  it("should trigger terminate + re-register within delay", async () => {
+    const { fn, terminated } = makeSpawn();
+    const sup = new Supervisor({
+      config: { strategy: "one_for_one", baseRestartDelayMs: 10 },
+    });
+    sup.register("api-server", fn);
+
+    sup.requestGracefulRestart("api-server");
+    await sleep(80);
+
+    expect(terminated.length).toBeGreaterThan(0); // terminate was called
+    expect(fn.mock.calls.length).toBeGreaterThan(1); // re-spawned
+    await sup.stopAll();
+  });
+
+  it("should not restart if supervisor is stopped", async () => {
+    const { fn } = makeSpawn();
+    const sup = new Supervisor({
+      config: { strategy: "one_for_one", baseRestartDelayMs: 10 },
+    });
+    sup.register("w", fn);
+    await sup.stopAll();
+
+    const callsBeforeExit = fn.mock.calls.length;
+    sup.onWorkerExit("w", 1);
+    await sleep(60);
+    // No additional spawns after stopAll
+    expect(fn.mock.calls.length).toBe(callsBeforeExit);
+  });
+});
+
+// ─── Supervisor — stop individual worker ─────────────────────────────────────
+
+describe("Supervisor — stop single worker", () => {
+  it("should remove worker from statuses after stop()", async () => {
+    const { fn } = makeSpawn();
+    const sup = new Supervisor();
+    sup.register("to-stop", fn);
+    await sup.stop("to-stop");
+
+    const statuses = sup.getWorkerStatuses();
+    expect(statuses.find((s) => s.id === "to-stop")).toBeUndefined();
+  });
+
+  it("should call terminate on the worker instance", async () => {
+    const { fn, terminated } = makeSpawn();
+    const sup = new Supervisor();
+    sup.register("terminate-me", fn);
+    await sup.stop("terminate-me");
+    expect(terminated).toHaveLength(1);
+  });
+});