muonroi-cli 1.2.0

package/src/ee/intercept.ts

@@ -0,0 +1,132 @@
+import { getCachedAuthToken, getCachedServerBaseUrl, loadEEAuthToken, refreshAuthToken } from "./auth.js";
+import { getTenantId } from "./tenant.js";
+import type { CreateEEClientOpts } from "./client.js";
+import { createEEClient } from "./client.js";
+import { emitMatches } from "./render.js";
+import { buildScope } from "./scope.js";
+import type { InterceptRequest, InterceptResponse, Scope } from "./types.js";
+
+// ─── Surfaced-state tracking for prompt-stale reconciliation ─────────────────
+let _lastSurfacedIds: string[] = [];
+let _lastSurfacedTimestamp: string | null = null;
+
+/**
+ * Returns the last surfaced suggestion IDs and timestamp from the most recent
+ * intercept call that returned matches. Used by prompt-stale reconciliation
+ * callers (compact, clear, session-end).
+ */
+export function getLastSurfacedState(): { surfacedIds: string[]; timestamp: string } {
+  return {
+    surfacedIds: [..._lastSurfacedIds],
+    timestamp: _lastSurfacedTimestamp ?? new Date().toISOString(),
+  };
+}
+
+/**
+ * Allows non-HTTP code paths (e.g. PIL Layer 3 bridge search) to register
+ * point IDs they injected into the prompt. These IDs join the HTTP-intercept
+ * surfaced IDs for prompt-stale reconciliation.
+ */
+export function updateLastSurfacedState(ids: string[]): void {
+  if (ids.length === 0) return;
+  _lastSurfacedIds = [...ids];
+  _lastSurfacedTimestamp = new Date().toISOString();
+}
+
+/**
+ * Resets surfaced state to empty. Called after prompt-stale reconciliation
+ * dispatches so the same IDs are not re-reported on the next turn.
+ */
+export function resetLastSurfacedState(): void {
+  _lastSurfacedIds = [];
+  _lastSurfacedTimestamp = null;
+}
+
+/**
+ * Module-level default EE client instance (lazy-initialized on first use).
+ * Use setDefaultEEClient() to inject a custom client (e.g. in tests or at boot
+ * after loading auth token from config).
+ */
+let _defaultClient: ReturnType<typeof createEEClient> | null = null;
+
+export function setDefaultEEClient(c: ReturnType<typeof createEEClient>): void {
+  _defaultClient = c;
+}
+
+export function getDefaultEEClient(): ReturnType<typeof createEEClient> {
+  if (!_defaultClient)
+    _defaultClient = createEEClient({
+      baseUrl: getCachedServerBaseUrl() ?? undefined,
+      authToken: getCachedAuthToken() ?? undefined,
+    });
+  return _defaultClient;
+}
+
+/**
+ * Call the EE intercept endpoint using the default client.
+ * Blocks until a decision is received or the timeout elapses (falls back to allow).
+ *
+ * Phase 1: requires tenantId + scope explicitly.
+ * - On 401 (surfaced as reason='auth-required'): refreshes token, rebuilds client, retries once.
+ * - On allow + matches[]: emits rendered ⚠ lines via render sink.
+ */
+export async function intercept(req: InterceptRequest, opts?: CreateEEClientOpts): Promise<InterceptResponse> {
+  const client = opts ? createEEClient(opts) : getDefaultEEClient();
+  let resp = await client.intercept(req);
+
+  // 401 refresh path: client surfaces 401 as { decision: 'allow', reason: 'auth-required' }
+  if ((resp as any).reason === "auth-required") {
+    await refreshAuthToken();
+    _defaultClient = createEEClient({
+      authToken: getCachedAuthToken() ?? undefined,
+    });
+    resp = await getDefaultEEClient().intercept(req);
+  }
+
+  // Emit rendered warnings for allow + matches
+  if (resp.decision === "allow" && resp.matches) {
+    emitMatches(resp.matches);
+  }
+
+  // Track surfaced IDs for prompt-stale reconciliation
+  if (resp.surfacedIds && resp.surfacedIds.length > 0) {
+    _lastSurfacedIds = [...resp.surfacedIds];
+    _lastSurfacedTimestamp = new Date().toISOString();
+  } else if (resp.matches && resp.matches.length > 0) {
+    _lastSurfacedIds = resp.matches.map((m) => m.principle_uuid);
+    _lastSurfacedTimestamp = new Date().toISOString();
+  }
+
+  return resp;
+}
+
+/**
+ * @deprecated — pass tenantId + scope explicitly. This helper fills defaults
+ * for Phase 0 callers that haven't been migrated yet.
+ *
+ * Fills tenantId='local' and scope (computed via buildScope({ cwd })) when omitted.
+ */
+export async function interceptWithDefaults(
+  req: Omit<InterceptRequest, "tenantId" | "scope"> & Partial<Pick<InterceptRequest, "tenantId" | "scope">>,
+): Promise<InterceptResponse> {
+  const tenantId = req.tenantId ?? getTenantId();
+  const scope: Scope = req.scope ?? (await buildScope({ cwd: req.cwd }));
+  return intercept({
+    toolName: req.toolName,
+    toolInput: req.toolInput,
+    cwd: req.cwd,
+    tenantId,
+    scope,
+  });
+}
+
+/**
+ * Bootstrap the EE client with auth token from ~/.experience/config.json.
+ * Called once at session boot.
+ */
+export async function bootstrapEEClient(home?: string): Promise<void> {
+  await loadEEAuthToken({ home });
+  _defaultClient = createEEClient({
+    authToken: getCachedAuthToken() ?? undefined,
+  });
+}

package/src/ee/judge.test.ts

@@ -0,0 +1,157 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { fireFeedback, type JudgeContext, judge } from "./judge.js";
+import type { InterceptMatch } from "./types.js";
+
+// Mock the intercept module to control getDefaultEEClient
+const mockFeedback = vi.fn();
+const mockTouch = vi.fn();
+vi.mock("./intercept.js", () => ({
+  getDefaultEEClient: () => ({
+    feedback: mockFeedback,
+    touch: mockTouch,
+  }),
+}));
+
+function makeMatch(overrides: Partial<InterceptMatch> = {}): InterceptMatch {
+  return {
+    principle_uuid: "P1",
+    embedding_model_version: "v1",
+    confidence: 0.9,
+    why: "test reason",
+    message: "test message",
+    scope_label: "global",
+    last_matched_at: new Date().toISOString(),
+    ...overrides,
+  };
+}
+
+function makeCtx(overrides: Partial<JudgeContext> = {}): JudgeContext {
+  return {
+    warningResponse: {
+      decision: "allow",
+      matches: [makeMatch()],
+    },
+    toolName: "Edit",
+    outcome: { success: true, durationMs: 50 },
+    cwdMatchedAtPretool: true,
+    diffPresent: false,
+    tenantId: "local",
+    ...overrides,
+  };
+}
+
+describe("judge() deterministic classifier", () => {
+  it("no warningResponse.matches returns IRRELEVANT", () => {
+    const ctx = makeCtx({ warningResponse: { decision: "allow" } });
+    expect(judge(ctx)).toBe("IRRELEVANT");
+  });
+
+  it("empty matches array returns IRRELEVANT", () => {
+    const ctx = makeCtx({
+      warningResponse: { decision: "allow", matches: [] },
+    });
+    expect(judge(ctx)).toBe("IRRELEVANT");
+  });
+
+  it("cwdMatchedAtPretool=false returns IRRELEVANT", () => {
+    const ctx = makeCtx({ cwdMatchedAtPretool: false });
+    expect(judge(ctx)).toBe("IRRELEVANT");
+  });
+
+  it("successful outcome with matches returns FOLLOWED", () => {
+    const ctx = makeCtx();
+    expect(judge(ctx)).toBe("FOLLOWED");
+  });
+
+  it("failed outcome with matches returns IGNORED", () => {
+    const ctx = makeCtx({
+      outcome: { success: false, durationMs: 10 },
+    });
+    expect(judge(ctx)).toBe("IGNORED");
+  });
+
+  it("expectedBehavior=should-not-edit AND diffPresent=true returns IGNORED even with success", () => {
+    const ctx = makeCtx({
+      warningResponse: {
+        decision: "allow",
+        matches: [makeMatch({ expectedBehavior: "should-not-edit" })],
+      },
+      diffPresent: true,
+    });
+    expect(judge(ctx)).toBe("IGNORED");
+  });
+
+  it("expectedBehavior=should-not-edit AND diffPresent=false returns FOLLOWED", () => {
+    const ctx = makeCtx({
+      warningResponse: {
+        decision: "allow",
+        matches: [makeMatch({ expectedBehavior: "should-not-edit" })],
+      },
+      diffPresent: false,
+    });
+    expect(judge(ctx)).toBe("FOLLOWED");
+  });
+
+  it("null warningResponse returns IRRELEVANT", () => {
+    const ctx = makeCtx({ warningResponse: null });
+    expect(judge(ctx)).toBe("IRRELEVANT");
+  });
+});
+
+describe("fireFeedback()", () => {
+  beforeEach(() => {
+    mockFeedback.mockClear();
+    mockTouch.mockClear();
+  });
+
+  it("FOLLOWED: calls feedback() once per match AND touch() once per match", () => {
+    const ctx = makeCtx({
+      warningResponse: {
+        decision: "allow",
+        matches: [makeMatch({ principle_uuid: "P1" })],
+      },
+    });
+    fireFeedback(ctx);
+    expect(mockFeedback).toHaveBeenCalledOnce();
+    expect(mockFeedback).toHaveBeenCalledWith(
+      expect.objectContaining({
+        principle_uuid: "P1",
+        classification: "FOLLOWED",
+        tool_name: "Edit",
+      }),
+    );
+    expect(mockTouch).toHaveBeenCalledOnce();
+    expect(mockTouch).toHaveBeenCalledWith("P1", "local");
+  });
+
+  it("IGNORED: calls feedback() but NOT touch()", () => {
+    const ctx = makeCtx({
+      outcome: { success: false, durationMs: 10 },
+    });
+    fireFeedback(ctx);
+    expect(mockFeedback).toHaveBeenCalledOnce();
+    expect(mockFeedback).toHaveBeenCalledWith(expect.objectContaining({ classification: "IGNORED" }));
+    expect(mockTouch).not.toHaveBeenCalled();
+  });
+
+  it("IRRELEVANT (no matches): does not call feedback or touch", () => {
+    const ctx = makeCtx({ warningResponse: null });
+    fireFeedback(ctx);
+    expect(mockFeedback).not.toHaveBeenCalled();
+    expect(mockTouch).not.toHaveBeenCalled();
+  });
+
+  it("multiple matches: calls feedback and touch for each", () => {
+    const ctx = makeCtx({
+      warningResponse: {
+        decision: "allow",
+        matches: [makeMatch({ principle_uuid: "P1" }), makeMatch({ principle_uuid: "P2" })],
+      },
+    });
+    fireFeedback(ctx);
+    expect(mockFeedback).toHaveBeenCalledTimes(2);
+    expect(mockTouch).toHaveBeenCalledTimes(2);
+    expect(mockTouch).toHaveBeenCalledWith("P1", "local");
+    expect(mockTouch).toHaveBeenCalledWith("P2", "local");
+  });
+});

package/src/ee/judge.ts

@@ -0,0 +1,68 @@
+/**
+ * src/ee/judge.ts
+ *
+ * Deterministic auto-judge classifier (EE-09).
+ * Classifies every tool call as FOLLOWED | IGNORED | IRRELEVANT using
+ * deterministic rules — no LLM involved.
+ *
+ * fireFeedback() fires /api/feedback fire-and-forget per match, and
+ * /api/principle/touch on FOLLOWED matches (EE-10 decay refresh).
+ */
+
+import { getDefaultEEClient } from "./intercept.js";
+import type { Classification, InterceptResponse, PostToolPayload } from "./types.js";
+
+export interface JudgeContext {
+  warningResponse: InterceptResponse | null;
+  toolName: string;
+  outcome: PostToolPayload["outcome"];
+  cwdMatchedAtPretool: boolean;
+  diffPresent: boolean;
+  tenantId: string;
+}
+
+/**
+ * Deterministic classification rules (from RESEARCH Auto-Judge Deterministic Rules):
+ *
+ * 1. No matches or cwd mismatch → IRRELEVANT
+ * 2. Outcome failed → IGNORED
+ * 3. Any match has expectedBehavior='should-not-edit' AND diff present → IGNORED
+ * 4. Otherwise → FOLLOWED
+ */
+export function judge(ctx: JudgeContext): Classification {
+  if (!ctx.warningResponse?.matches?.length || !ctx.cwdMatchedAtPretool) {
+    return "IRRELEVANT";
+  }
+  if (!ctx.outcome.success) {
+    return "IGNORED";
+  }
+  if (ctx.warningResponse.matches.some((m) => m.expectedBehavior === "should-not-edit" && ctx.diffPresent)) {
+    return "IGNORED";
+  }
+  return "FOLLOWED";
+}
+
+/**
+ * Fire feedback for each match in the warning response.
+ * - Always calls /api/feedback per match (fire-and-forget).
+ * - On FOLLOWED, also calls /api/principle/touch per match (EE-10 decay refresh).
+ *
+ * B-4 invariant: returns void synchronously. All HTTP calls are fire-and-forget.
+ */
+export function fireFeedback(ctx: JudgeContext): void {
+  const cls = judge(ctx);
+  const matches = ctx.warningResponse?.matches ?? [];
+  const client = getDefaultEEClient();
+  for (const m of matches) {
+    client.feedback({
+      principle_uuid: m.principle_uuid,
+      classification: cls,
+      tool_name: ctx.toolName,
+      duration_ms: ctx.outcome.durationMs ?? 0,
+      tenantId: ctx.tenantId,
+    });
+    if (cls === "FOLLOWED") {
+      client.touch(m.principle_uuid, ctx.tenantId);
+    }
+  }
+}

package/src/ee/offline-queue.test.ts

@@ -0,0 +1,351 @@
+/**
+ * Unit + integration tests for offline-queue module.
+ *
+ * Tests cover all 10 behaviors:
+ *  1. enqueue() creates queue directory lazily
+ *  2. enqueue() writes correct JSON content
+ *  3. enqueue() enforces 100-entry cap by deleting oldest
+ *  4. getQueueDir() returns correct path
+ *  5. drainQueue() replays entries in FIFO order
+ *  6. drainQueue() stops on failure, leaves remaining entries
+ *  7. drainQueue() handles non-existent queue directory
+ *  8. drainQueue() discards corrupt JSON files
+ *  9. Filename format matches /^\d+-[a-z0-9]{4}\.json$/
+ * 10. drainQueue() is fire-and-forget (returns void)
+ */
+import { mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { startStubEEServer } from "../__test-stubs__/ee-server.js";
+import {
+  drainQueue,
+  drainQueueAsync,
+  enqueue,
+  getQueueDir,
+} from "./offline-queue.js";
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+let tmpDir: string;
+
+beforeEach(async () => {
+  // Create isolated temp directory for each test
+  const base = path.join(os.tmpdir(), "queue-test-");
+  // Use a unique timestamp+random suffix
+  const suffix = `${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+  tmpDir = base + suffix;
+  await mkdir(tmpDir, { recursive: true });
+});
+
+afterEach(async () => {
+  await rm(tmpDir, { recursive: true, force: true });
+});
+
+/**
+ * Helper: get the ee-offline-queue dir inside tmpDir.
+ */
+function queueDir(): string {
+  return getQueueDir(tmpDir);
+}
+
+/**
+ * Helper: write N pre-populated queue files with sequential timestamps.
+ */
+async function populateQueue(count: number, startTs = 1000): Promise<string[]> {
+  const dir = queueDir();
+  await mkdir(dir, { recursive: true });
+  const filenames: string[] = [];
+  for (let i = 0; i < count; i++) {
+    const ts = startTs + i;
+    const filename = `${ts}-test.json`;
+    const entry = {
+      endpoint: "/api/feedback",
+      body: { i },
+      enqueuedAt: ts,
+    };
+    await writeFile(path.join(dir, filename), JSON.stringify(entry), "utf8");
+    filenames.push(filename);
+  }
+  return filenames;
+}
+
+// ─── Test 1: enqueue() creates queue directory lazily ─────────────────────────
+
+describe("enqueue()", () => {
+  it("creates the queue directory lazily on first call", async () => {
+    // Queue dir should NOT exist before enqueue
+    const dir = queueDir();
+    const files = await readdir(dir).catch(() => null);
+    expect(files).toBeNull(); // dir does not exist yet
+
+    // Call enqueue — should create dir
+    await enqueue(
+      { endpoint: "/api/feedback", body: { test: 1 }, enqueuedAt: 1000 },
+      tmpDir,
+    );
+
+    // Dir should now exist
+    const filesAfter = await readdir(dir);
+    expect(Array.isArray(filesAfter)).toBe(true);
+  });
+
+  // ─── Test 9: Filename format ───────────────────────────────────────────────
+
+  it("creates exactly 1 file with correct filename pattern after one enqueue", async () => {
+    await enqueue(
+      { endpoint: "/api/feedback", body: { test: 1 }, enqueuedAt: 1000 },
+      tmpDir,
+    );
+
+    const files = await readdir(queueDir());
+    expect(files).toHaveLength(1);
+    expect(files[0]).toMatch(/^\d+-[a-z0-9]{4}\.json$/);
+  });
+
+  // ─── Test 2: enqueue() writes correct JSON content ────────────────────────
+
+  it("writes correct JSON content matching the input entry", async () => {
+    const entry = {
+      endpoint: "/api/feedback",
+      body: { test: 1 },
+      enqueuedAt: 1000,
+    };
+    await enqueue(entry, tmpDir);
+
+    const dir = queueDir();
+    const files = await readdir(dir);
+    const raw = await import("node:fs/promises").then((fs) =>
+      fs.readFile(path.join(dir, files[0]), "utf8"),
+    );
+    const parsed = JSON.parse(raw);
+
+    expect(parsed).toEqual(entry);
+  });
+
+  // ─── Test 3: enqueue() enforces 100-entry cap ─────────────────────────────
+
+  it("enforces 100-entry cap: deletes oldest when queue is at capacity", async () => {
+    // Pre-populate with exactly 100 files
+    const existing = await populateQueue(100, 1000);
+    const oldestFile = existing[0]; // timestamp 1000-test.json
+
+    // Enqueue one more entry
+    await enqueue(
+      {
+        endpoint: "/api/feedback",
+        body: { new: true },
+        enqueuedAt: 99999,
+      },
+      tmpDir,
+    );
+
+    const files = await readdir(queueDir());
+
+    // Should still have exactly 100 files
+    expect(files).toHaveLength(100);
+
+    // Oldest file should be gone
+    expect(files).not.toContain(oldestFile);
+
+    // New file should exist (it has a fresh timestamp prefix via makeFilename())
+    const newFiles = files.filter((f) => !existing.includes(f));
+    expect(newFiles).toHaveLength(1);
+  });
+});
+
+// ─── Test 4: getQueueDir() returns correct path ───────────────────────────────
+
+describe("getQueueDir()", () => {
+  it("returns path under os.homedir() when no override given", () => {
+    const result = getQueueDir();
+    expect(result).toBe(
+      path.join(os.homedir(), ".muonroi-cli", "ee-offline-queue"),
+    );
+  });
+
+  it("returns path under homeOverride when provided", () => {
+    const result = getQueueDir("/tmp/test");
+    expect(result).toBe(
+      path.join("/tmp/test", ".muonroi-cli", "ee-offline-queue"),
+    );
+  });
+});
+
+// ─── Test 5: drainQueue() replays entries in FIFO order ───────────────────────
+
+describe("drainQueueAsync()", () => {
+  it("replays entries in FIFO order and deletes them after success", async () => {
+    // Pre-populate 3 entries with distinct timestamps
+    await populateQueue(3, 1000);
+
+    const stub = await startStubEEServer({ feedback: () => {} });
+
+    try {
+      await drainQueueAsync(
+        fetch,
+        { "Content-Type": "application/json" },
+        `http://127.0.0.1:${stub.port}`,
+        tmpDir,
+      );
+
+      // 3 requests received in order
+      expect(stub.calls.feedback).toHaveLength(3);
+      expect(stub.calls.feedback[0].enqueuedAt ?? stub.calls.feedback[0].i).toBeDefined();
+
+      // FIFO: first enqueued (ts=1000) should come first
+      const receivedEnqueuedAts = stub.calls.feedback.map((b: any) => b.enqueuedAt ?? b.i);
+      expect(receivedEnqueuedAts[0]).toBeLessThan(receivedEnqueuedAts[1]);
+      expect(receivedEnqueuedAts[1]).toBeLessThan(receivedEnqueuedAts[2]);
+
+      // All files deleted after successful replay
+      const remainingFiles = await readdir(queueDir()).catch(() => []);
+      expect(remainingFiles).toHaveLength(0);
+    } finally {
+      await stub.stop();
+    }
+  });
+
+  // ─── Test 6: drainQueue() stops on failure, leaves remaining ──────────────
+
+  it("stops on 2nd entry failure and leaves 2nd + 3rd entries on disk", async () => {
+    await populateQueue(3, 1000);
+
+    let callCount = 0;
+    const stub = await startStubEEServer({
+      feedback: () => {
+        callCount++;
+      },
+    });
+
+    // Override the server to return 500 on 2nd call
+    // We'll track calls and use a custom stub that serves 500 on 2nd request
+    await stub.stop();
+
+    // Build a minimal stub that returns 500 on 2nd POST to /api/feedback
+    const { createServer } = await import("node:http");
+    let reqCount = 0;
+    const customServer = createServer((req, res) => {
+      if (req.url === "/api/feedback" && req.method === "POST") {
+        reqCount++;
+        const chunks: Buffer[] = [];
+        req.on("data", (c: Buffer) => chunks.push(c));
+        req.on("end", () => {
+          if (reqCount === 2) {
+            res.writeHead(500);
+            res.end("error");
+          } else {
+            res.writeHead(200);
+            res.end("ok");
+          }
+        });
+      } else {
+        res.writeHead(404);
+        res.end();
+      }
+    });
+
+    await new Promise<void>((resolve) =>
+      customServer.listen(0, "127.0.0.1", () => resolve()),
+    );
+    const addr = customServer.address();
+    const port =
+      typeof addr === "object" && addr ? (addr as { port: number }).port : 0;
+
+    try {
+      await drainQueueAsync(
+        fetch,
+        { "Content-Type": "application/json" },
+        `http://127.0.0.1:${port}`,
+        tmpDir,
+      );
+
+      // 1st success, 2nd failure → should have made 2 requests total
+      expect(reqCount).toBe(2);
+
+      // 2nd and 3rd files remain on disk (1st was deleted on success)
+      const remainingFiles = await readdir(queueDir());
+      expect(remainingFiles).toHaveLength(2);
+    } finally {
+      await new Promise<void>((resolve) => customServer.close(() => resolve()));
+    }
+  });
+
+  // ─── Test 7: drainQueue() handles non-existent queue directory ────────────
+
+  it("returns cleanly when queue directory does not exist", async () => {
+    // No queue dir created — just call drainQueueAsync with a fresh tmpDir
+    await expect(
+      drainQueueAsync(
+        fetch,
+        { "Content-Type": "application/json" },
+        "http://127.0.0.1:9999",
+        tmpDir,
+      ),
+    ).resolves.toBeUndefined();
+  });
+
+  // ─── Test 8: drainQueue() discards corrupt JSON files ─────────────────────
+
+  it("discards corrupt JSON files and replays valid entries after them", async () => {
+    const dir = queueDir();
+    await mkdir(dir, { recursive: true });
+
+    // Write corrupt file first (older timestamp)
+    const corruptFile = "1000-bad1.json";
+    await writeFile(path.join(dir, corruptFile), "NOT VALID JSON {{{{", "utf8");
+
+    // Write valid entry after (newer timestamp)
+    const validEntry = {
+      endpoint: "/api/feedback",
+      body: { valid: true },
+      enqueuedAt: 2000,
+    };
+    await writeFile(
+      path.join(dir, "2000-good.json"),
+      JSON.stringify(validEntry),
+      "utf8",
+    );
+
+    const stub = await startStubEEServer({ feedback: () => {} });
+
+    try {
+      await drainQueueAsync(
+        fetch,
+        { "Content-Type": "application/json" },
+        `http://127.0.0.1:${stub.port}`,
+        tmpDir,
+      );
+
+      // Corrupt file should be deleted
+      const remaining = await readdir(dir);
+      expect(remaining).not.toContain(corruptFile);
+
+      // Valid entry should have been replayed
+      expect(stub.calls.feedback).toHaveLength(1);
+      expect(stub.calls.feedback[0]).toEqual(validEntry.body);
+
+      // Valid file should be deleted after replay
+      expect(remaining).toHaveLength(0);
+    } finally {
+      await stub.stop();
+    }
+  });
+});
+
+// ─── Test 10: drainQueue() is fire-and-forget ─────────────────────────────────
+
+describe("drainQueue() fire-and-forget wrapper", () => {
+  it("returns void (undefined), not a Promise", () => {
+    // Call drainQueue (the fire-and-forget wrapper) — should return undefined immediately
+    const result = drainQueue(
+      fetch,
+      { "Content-Type": "application/json" },
+      "http://127.0.0.1:9999",
+      tmpDir,
+    );
+
+    // drainQueue() must return void (undefined), not a Promise
+    expect(result).toBeUndefined();
+  });
+});