fix: report real counts, and mark every page that is not the whole story

From the Hermes plugin's closed PRs. Of the five I had not already
reviewed, one applied directly, two were already handled, and two do not
exist here.

hookdeck_recent_deliveries returned a capped page of open Issues with no
total and no marker. Asked "what needs attention?", a model sees twenty
and has nothing to tell it there are four hundred — so it reports what it
can see, which for a tool whose job is saying what is true is the worst
way to be wrong. It now returns `openIssuesTotal` from the count
endpoint, plus `openIssuesTruncated` when the page is short of it, and
`localTruncated` for the local records.

hookdeck_status.deadLetters is the local log's true size, but the log
evicts oldest-first at its cap, so a full log reports a floor rather than
a total. `deadLettersIsAtLeast: true` now says so. hookdeck_status's
issue count and hookdeck_issues' total were already counted rather than
measured.

Not applicable: the CI gate reading the legacy commit-status API (we
gate on the workflow itself, and have no release gate to get wrong) and
the dashboard bundle tests (there is no dashboard here). The tunnel
escalation from #7 is the same change already made.

Also borrowed the practice rather than a fix: every safety-critical guard
was mutation-checked by breaking it and confirming the suite fails. All
eight are covered — the pause ceiling, the allowMutations gate, the
read-only refusal, the attempt-count ceiling, the pre-verification
dead-letter gate, the backoff reset rule, the retry-rule coverage check
and the new project-mismatch check — each caught by between one and four
tests.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: garethx

docs/agent-tools.md

@@ -85,3 +85,11 @@ Payload text from a webhook is third-party input, and the tools treat it that wa
 - The delivered body is **opt-in** (`includeBody`), truncated at 4,000 characters, and labelled as data rather than presented as something addressed to the reader.
 - The `hookdeck listen` child's output is scrubbed of the API key as it is captured, not as it is read — that output is surfaced by `hookdeck_status` and we do not write it, so a future CLI version echoing a key into a banner would otherwise land it in a model's context with nothing here having changed.
 - A test asserts that no configured secret appears in *any* tool's result, so the next tool added inherits the check.
+
+## Counts are counted
+
+A status tool that returns a page and lets the reader infer a total is worse than one that says nothing: a model asked "what needs attention?" will report what it can see as though it were everything.
+
+- `hookdeck_status.openIssues` and `hookdeck_issues`' `total` come from Hookdeck's count endpoint, not from the length of a page.
+- `hookdeck_recent_deliveries` returns `openIssuesTotal` beside the page it shows, and an `openIssuesTruncated` note whenever the two differ. The local records get the same treatment via `localTruncated`.
+- `hookdeck_status.deadLetters` is the local log's true size, but the log evicts oldest-first at its cap — so once it is full, `deadLettersIsAtLeast: true` says the number is a floor. A floor reported as a floor beats a ceiling reported as a total.

src/store/deadletter.ts

@@ -63,6 +63,8 @@ export interface DeadLetterLog {
   ): Promise<DeadLetterRecord>;
   list(limit?: number): DeadLetterRecord[];
   count(): number;
+  /** The cap at which the log evicts oldest-first, so callers can say "at least". */
+  capacity(): number;
   close(): Promise<void>;
   stats(): { entries: number; persistence: PersistenceState };
 }
@@ -143,6 +145,10 @@ export async function createDeadLetterLog(
       return store.values().length;
     },
 
+    capacity() {
+      return maxEntries;
+    },
+
     async close() {
       await store.close();
     },

src/tools/deliveries.ts

@@ -20,10 +20,12 @@ export async function recentDeliveriesHandler(
 
   // Filter first, then limit: filtering a pre-truncated page silently returns
   // fewer rows than asked for.
-  const local = deps.deadLetter
+  const matching = deps.deadLetter
     .list(500)
-    .filter((r) => params.routeId === undefined || r.routeId === params.routeId)
-    .slice(0, limit);
+    .filter(
+      (r) => params.routeId === undefined || r.routeId === params.routeId,
+    );
+  const local = matching.slice(0, limit);
 
   // Joined rather than returned separately: Hookdeck's view and ours disagree
   // precisely when something interesting happened.
@@ -54,6 +56,7 @@ export async function recentDeliveriesHandler(
   // place to be wrong.
   let issues: ReturnType<typeof summariseIssue>[] | null = null;
   let issuesNote: string | undefined;
+  let openIssuesTotal: number | null = null;
   if (deps.client !== undefined) {
     const result = await deps.client.listIssues({
       status: "OPENED",
@@ -62,6 +65,12 @@ export async function recentDeliveriesHandler(
     if (result.ok) {
       const names = await resolveConnectionNames(deps.client, result.data);
       issues = result.data.map((i) => summariseIssue(i, names));
+
+      // Counted, never inferred from the page. A tool that returns twenty of
+      // four hundred issues without saying so leaves a model to guess at the
+      // total, and it will guess from what it can see.
+      const total = await deps.client.countIssues({ status: "OPENED" });
+      if (total.ok) openIssuesTotal = total.data;
     } else {
       issuesNote = `Could not read Hookdeck Issues: ${result.message}`;
     }
@@ -80,13 +89,30 @@ export async function recentDeliveriesHandler(
     source: deps.source,
     // The real DLQ.
     openIssues: issues,
+    /**
+     * How many there actually are, counted rather than measured from the page.
+     * Null when it could not be counted, which is different from zero.
+     */
+    openIssuesTotal,
+    ...(issues !== null &&
+    openIssuesTotal !== null &&
+    issues.length < openIssuesTotal
+      ? {
+          openIssuesTruncated: `Showing ${issues.length} of ${openIssuesTotal} open issues. Raise limit, or use hookdeck_issues.`,
+        }
+      : {}),
     /**
      * Failures Hookdeck cannot see, because we had already answered 2xx when
      * they happened. No Issue will ever open for these.
      */
     unreportedFailures: postAck,
     /** Local mirror of failures Hookdeck also recorded; prefer the Issue. */
     locallyRecorded: rows.filter((r) => r.hookdeckVisible === true),
+    ...(matching.length > local.length
+      ? {
+          localTruncated: `Showing ${local.length} of ${matching.length} local records. Raise limit to see more.`,
+        }
+      : {}),
     ...(issuesNote !== undefined ? { note: issuesNote } : {}),
     ...(issues !== null && issues.length === 0 && postAck.length === 0
       ? {

src/tools/status.ts

@@ -68,6 +68,14 @@ export async function statusHandler(
         : {}),
     },
     deadLetters: deps.deadLetter.count(),
+    /**
+     * The log evicts oldest-first at its cap, so a count sitting at the cap is
+     * a floor rather than a total. Said out loud: a model reporting "500
+     * failures" as the number is worse than one reporting "at least 500".
+     */
+    ...(deps.deadLetter.count() >= deps.deadLetter.capacity()
+      ? { deadLettersIsAtLeast: true }
+      : {}),
     retryCancellations: deps.retryCancels?.() ?? null,
     transport: {
       mode: deps.config.transport.mode,

test/config-parse.test.ts

@@ -447,7 +447,9 @@ describe("project pinning", () => {
     const result = parseHookdeckConfig({
       signingSecret: "whsec",
       projectId: "tm_abc",
-      routes: { a: { source: "a", dispatch: { mode: "wake", sessionKey: "m" } } },
+      routes: {
+        a: { source: "a", dispatch: { mode: "wake", sessionKey: "m" } },
+      },
     });
     expect(result.ok).toBe(true);
     if (result.ok) expect(result.config.projectId).toBe("tm_abc");
@@ -457,9 +459,12 @@ describe("project pinning", () => {
     const result = parseHookdeckConfig({
       signingSecret: "whsec",
       transport: { mode: "cli", cliConfigPath: "/custom/config.toml" },
-      routes: { a: { source: "a", dispatch: { mode: "wake", sessionKey: "m" } } },
+      routes: {
+        a: { source: "a", dispatch: { mode: "wake", sessionKey: "m" } },
+      },
     });
     expect(result.ok).toBe(true);
-    if (result.ok) expect(result.config.transport.cliConfigPath).toBe("/custom/config.toml");
+    if (result.ok)
+      expect(result.config.transport.cliConfigPath).toBe("/custom/config.toml");
   });
 });

test/tools.test.ts

@@ -1509,3 +1509,88 @@ describe("doctor diagnoses a CLI/API-key project mismatch", () => {
     ).toBeUndefined();
   });
 });
+
+describe("counts are counted, never measured from a page", () => {
+  // A tool that returns twenty of four hundred without saying so leaves a
+  // model to guess the total, and it will guess from what it can see.
+  it("reports the real open-issue total alongside the page", async () => {
+    const d = await deps({
+      client: fakeClient({
+        countIssues: vi.fn(async () => ({ ok: true as const, data: 400 })),
+      }),
+    });
+    const result = await recentDeliveriesHandler(d, {});
+
+    expect(result.openIssuesTotal).toBe(400);
+    expect(result.openIssues).toHaveLength(1);
+    expect(String(result.openIssuesTruncated)).toMatch(/Showing 1 of 400/);
+  });
+
+  it("does not claim truncation when the page holds everything", async () => {
+    const d = await deps();
+    const result = await recentDeliveriesHandler(d, {});
+    expect(result.openIssuesTotal).toBe(1);
+    expect(result.openIssuesTruncated).toBeUndefined();
+  });
+
+  it("distinguishes an uncountable total from zero", async () => {
+    const d = await deps({
+      client: fakeClient({
+        countIssues: vi.fn(async () => ({
+          ok: false as const,
+          code: "api_error",
+          message: "boom",
+        })),
+      }),
+    });
+    expect((await recentDeliveriesHandler(d, {})).openIssuesTotal).toBeNull();
+  });
+
+  it("says how many local records it left out", async () => {
+    const d = await deps();
+    for (let i = 0; i < 30; i += 1) {
+      await d.deadLetter.record({
+        eventId: `evt_${i}`,
+        routeId: "stripe",
+        code: "c",
+        reason: "r",
+        retriesCancelled: false,
+        lastAttempt: true,
+      });
+    }
+    const result = await recentDeliveriesHandler(d, { limit: 5 });
+    expect(String(result.localTruncated)).toMatch(/Showing 5 of 30/);
+  });
+
+  it("marks a full dead-letter log as a floor, not a total", async () => {
+    // The log evicts oldest-first at its cap, so "500" is "at least 500".
+    const d = await deps();
+    const { createDeadLetterLog } = await import("../src/store/deadletter.js");
+    d.deadLetter = await createDeadLetterLog({ ttlHours: 168, maxEntries: 3 });
+    for (let i = 0; i < 5; i += 1) {
+      await d.deadLetter.record({
+        eventId: `evt_${i}`,
+        code: "c",
+        reason: "r",
+        retriesCancelled: false,
+        lastAttempt: true,
+      });
+    }
+
+    const result = await statusHandler(d, {});
+    expect(result.deadLetters).toBe(3);
+    expect(result.deadLettersIsAtLeast).toBe(true);
+  });
+
+  it("does not mark a log below its cap", async () => {
+    const d = await deps();
+    await d.deadLetter.record({
+      eventId: "evt_1",
+      code: "c",
+      reason: "r",
+      retriesCancelled: false,
+      lastAttempt: true,
+    });
+    expect((await statusHandler(d, {})).deadLettersIsAtLeast).toBeUndefined();
+  });
+});