fix(channels): make nack callbacks idempotent

Glucksberg · Glucksberg · commit 4583b9c0edb5 · 2026-07-12T03:38:07.000Z
diff --git a/src/channels/message/lifecycle.test.ts b/src/channels/message/lifecycle.test.ts
@@ -367,11 +367,36 @@ describe("message lifecycle primitives", () => {
 
     const nackError = new Error("offset failed");
     await ctx.nack(nackError);
+    await ctx.nack(new Error("duplicate failure"));
+    expect(onNack).toHaveBeenCalledTimes(1);
     expect(onNack).toHaveBeenCalledWith(nackError);
     expect(ctx.ackState).toBe("nacked");
     expect(ctx.nackErrorMessage).toBe("offset failed");
   });
 
+  it("retries nack callbacks after a failed attempt", async () => {
+    const onNack = vi
+      .fn<(error: unknown) => Promise<void>>()
+      .mockRejectedValueOnce(new Error("temporary failure"))
+      .mockResolvedValueOnce();
+    const ctx = createMessageReceiveContext({
+      id: "rx-nack-retry",
+      channel: "telegram",
+      message: { text: "hello" },
+      onNack,
+    });
+
+    await expect(ctx.nack(new Error("first failure"))).rejects.toThrow("temporary failure");
+    expect(ctx.ackState).toBe("pending");
+
+    const retryError = new Error("retry failure");
+    await ctx.nack(retryError);
+
+    expect(onNack).toHaveBeenCalledTimes(2);
+    expect(ctx.ackState).toBe("nacked");
+    expect(ctx.nackErrorMessage).toBe("retry failure");
+  });
+
   it("maps ack policies to lifecycle stages", () => {
     expect(shouldAckMessageAfterStage("after_receive_record", "receive_record")).toBe(true);
     expect(shouldAckMessageAfterStage("after_receive_record", "agent_dispatch")).toBe(false);
diff --git a/src/channels/message/receive.ts b/src/channels/message/receive.ts
@@ -88,6 +88,10 @@ export function createMessageReceiveContext<TMessage>(params: {
       delete ctx.nackErrorMessage;
     },
     nack: async (error) => {
+      // Nack callbacks are idempotent after completion but remain retryable after failure.
+      if (ctx.ackState === "nacked") {
+        return;
+      }
       await params.onNack?.(error);
       ctx.ackState = "nacked";
       ctx.nackErrorMessage = normalizeAckErrorMessage(error);
