@rubytech/create-maxy-code 0.1.590 → 0.1.592

package/payload/platform/plugins/scheduling/mcp/dist/tools/__tests__/scheduling-gate.test.js

@@ -17,7 +17,7 @@ vi.mock("../../lib/neo4j.js", () => ({
         close: vi.fn(async () => { }),
     }),
 }));
-import { runSchedulingGate, watermarkPath, readWatermarks, foldMailWatermarks, parseD1Count, digestBusy, } from "../scheduling-gate.js";
+import { runSchedulingGate, advanceGateMark, watermarkPath, readWatermarks, foldMailWatermarks, parseD1Count, digestBusy, } from "../scheduling-gate.js";
 const ACCOUNT = "20028fb5-0000-4000-8000-000000000000";
 const EVENT = "65ef758c-0000-4000-8000-000000000000";
 let platformRoot;
@@ -32,6 +32,8 @@ function quietSources(over = {}) {
         // Task 2653 — "quiet" for Telegram is an account that holds no inbound row at
         // all, which is what a fresh install answers.
         telegramInbound: async () => ({ newestInboundAt: null }),
+        // Task 2657 — "quiet" for the Outlook arm is a folder holding no message.
+        mailOutlook: async () => ({ newestReceivedAt: null }),
         ...over,
     };
 }
@@ -56,16 +58,17 @@ afterEach(() => {
     vi.doUnmock("imapflow");
     delete process.env.PLATFORM_PORT;
 });
-const run = (checks, sources, commit = false) => runSchedulingGate({ eventId: EVENT, checks, commit }, ACCOUNT, platformRoot, sources);
+const run = (checks, sources) => runSchedulingGate({ eventId: EVENT, checks }, ACCOUNT, platformRoot, sources);
 describe("d1 check", () => {
     const CHECK = { type: "d1", database: "bookings", sql: "SELECT count(*) FROM b" };
     it("is false on a zero count", async () => {
-        expect(await run([CHECK], quietSources())).toEqual({ hasWork: false, reasons: [] });
+        expect(await run([CHECK], quietSources())).toMatchObject({ hasWork: false, reasons: [], errored: [] });
     });
     it("is true on one row", async () => {
-        expect(await run([CHECK], quietSources({ d1: async () => 1 }))).toEqual({
+        expect(await run([CHECK], quietSources({ d1: async () => 1 }))).toMatchObject({
             hasWork: true,
             reasons: ["d1"],
+            errored: [],
         });
     });
     it("reports work rather than an error when the source is unreachable", async () => {
@@ -74,21 +77,25 @@ describe("d1 check", () => {
                 throw new Error("no cloudflare credentials");
             },
         });
-        expect(await run([CHECK], sources)).toEqual({ hasWork: true, reasons: ["d1"] });
+        expect(await run([CHECK], sources)).toMatchObject({
+            hasWork: true,
+            reasons: ["d1"],
+            errored: [{ kind: "d1", detail: "no cloudflare credentials" }],
+        });
     });
 });
 describe("mail check", () => {
     const CHECK = { type: "mail", mailbox: "ops@example.com" };
     it("is false when nothing sits above the watermark", async () => {
         seedWatermarks({ mail: { "ops@example.com|INBOX": { uid: 100, uidValidity: 1 } } });
-        expect(await run([CHECK], quietSources())).toEqual({ hasWork: false, reasons: [] });
+        expect(await run([CHECK], quietSources())).toMatchObject({ hasWork: false, reasons: [], errored: [] });
     });
     it("is true when a UID above the watermark matches", async () => {
         seedWatermarks({ mail: { "ops@example.com|INBOX": { uid: 100, uidValidity: 1 } } });
         const sources = quietSources({
             mail: async () => ({ matched: true, highestUid: 104, uidValidity: 1 }),
         });
-        expect(await run([CHECK], sources)).toEqual({ hasWork: true, reasons: ["mail"] });
+        expect(await run([CHECK], sources)).toMatchObject({ hasWork: true, reasons: ["mail"], errored: [] });
     });
     it("probes from UID 0 on a first run, so nothing already there is missed", async () => {
         const seen = [];
@@ -106,7 +113,7 @@ describe("mail check", () => {
         const sources = quietSources({
             mail: async () => ({ matched: false, highestUid: 100, uidValidity: 7 }),
         });
-        expect(await run([CHECK], sources)).toEqual({ hasWork: true, reasons: ["mail"] });
+        expect(await run([CHECK], sources)).toMatchObject({ hasWork: true, reasons: ["mail"], errored: [] });
     });
     it("keys the watermark by folder, so two folders of one mailbox never collide", async () => {
         seedWatermarks({ mail: { "ops@example.com|Archive": { uid: 100, uidValidity: 1 } } });
@@ -124,12 +131,12 @@ describe("mail check", () => {
 describe("whatsapp check", () => {
     it("status is false while connected", async () => {
         const check = { type: "whatsapp", scope: "status" };
-        expect(await run([check], quietSources())).toEqual({ hasWork: false, reasons: [] });
+        expect(await run([check], quietSources())).toMatchObject({ hasWork: false, reasons: [], errored: [] });
     });
     it("status is true while disconnected", async () => {
         const check = { type: "whatsapp", scope: "status" };
         const sources = quietSources({ whatsappStatus: async () => ({ connected: false }) });
-        expect(await run([check], sources)).toEqual({ hasWork: true, reasons: ["whatsapp"] });
+        expect(await run([check], sources)).toMatchObject({ hasWork: true, reasons: ["whatsapp"], errored: [] });
     });
     it("inbound is true only on a message received since the watermark", async () => {
         const check = { type: "whatsapp", scope: "inbound" };
@@ -137,7 +144,7 @@ describe("whatsapp check", () => {
         const sources = quietSources({
             whatsappInbound: async () => ({ latest: 1_754_000_900, newer: true }),
         });
-        expect(await run([check], sources)).toEqual({ hasWork: true, reasons: ["whatsapp"] });
+        expect(await run([check], sources)).toMatchObject({ hasWork: true, reasons: ["whatsapp"], errored: [] });
     });
     it("inbound passes the stored watermark to the source", async () => {
         const check = { type: "whatsapp", scope: "inbound" };
@@ -157,15 +164,15 @@ describe("calendar check", () => {
     const CHECK = { type: "calendar", connector: "google" };
     it("is false on an unchanged digest", async () => {
         seedWatermarks({ calendar: { digest: "DIGEST-A" } });
-        expect(await run([CHECK], quietSources())).toEqual({ hasWork: false, reasons: [] });
+        expect(await run([CHECK], quietSources())).toMatchObject({ hasWork: false, reasons: [], errored: [] });
     });
     it("is true on a changed digest", async () => {
         seedWatermarks({ calendar: { digest: "DIGEST-A" } });
         const sources = quietSources({ calendarDigest: async () => "DIGEST-B" });
-        expect(await run([CHECK], sources)).toEqual({ hasWork: true, reasons: ["calendar"] });
+        expect(await run([CHECK], sources)).toMatchObject({ hasWork: true, reasons: ["calendar"], errored: [] });
     });
     it("is true on a first run, when nothing has been committed yet", async () => {
-        expect(await run([CHECK], quietSources())).toEqual({ hasWork: true, reasons: ["calendar"] });
+        expect(await run([CHECK], quietSources())).toMatchObject({ hasWork: true, reasons: ["calendar"], errored: [] });
     });
 });
 describe("digestBusy", () => {
@@ -222,44 +229,49 @@ describe("all four together", () => {
             mail: { "ops@example.com|INBOX": { uid: 100, uidValidity: 1 } },
             calendar: { digest: "DIGEST-A" },
         });
-        expect(await run(ALL, quietSources())).toEqual({ hasWork: false, reasons: [] });
+        expect(await run(ALL, quietSources())).toMatchObject({ hasWork: false, reasons: [], errored: [] });
     });
     it("one noisy source is enough, and names only itself", async () => {
         seedWatermarks({
             mail: { "ops@example.com|INBOX": { uid: 100, uidValidity: 1 } },
             calendar: { digest: "DIGEST-A" },
         });
-        expect(await run(ALL, quietSources({ d1: async () => 2 }))).toEqual({
+        expect(await run(ALL, quietSources({ d1: async () => 2 }))).toMatchObject({
             hasWork: true,
             reasons: ["d1"],
+            errored: [],
         });
     });
 });
-describe("commit", () => {
+// Task 2663 — the advance is the dispatcher's, so it is tested through
+// `advanceGateMark` against the readings a real gate call returned. The old
+// `commit` describe drove the same ground through a parameter the agent set.
+describe("advanceGateMark", () => {
     const ALL = [
         { type: "mail", mailbox: "ops@example.com" },
         { type: "d1", database: "bookings", sql: "SELECT count(*) FROM b" },
         { type: "whatsapp", scope: "inbound" },
         { type: "calendar", connector: "google" },
     ];
-    it("a plain call leaves the file bytes unchanged", async () => {
+    it("the gate itself leaves the file bytes unchanged", async () => {
         seedWatermarks({ calendar: { digest: "DIGEST-A" } });
         const path = watermarkPath(EVENT, platformRoot);
         const before = readFileSync(path);
         await run(ALL, quietSources({ calendarDigest: async () => "DIGEST-B" }));
         expect(readFileSync(path).equals(before)).toBe(true);
     });
-    it("a plain call on a first run writes no file at all", async () => {
+    it("the gate on a first run writes no file at all", async () => {
         await run(ALL, quietSources());
         expect(existsSync(watermarkPath(EVENT, platformRoot))).toBe(false);
     });
-    it("advances every watermark named in checks", async () => {
+    it("advances every watermark the gate read", async () => {
         const sources = quietSources({
             mail: async () => ({ matched: true, highestUid: 250, uidValidity: 9 }),
             whatsappInbound: async () => ({ latest: 1_754_009_999, newer: true }),
             calendarDigest: async () => "DIGEST-Z",
         });
-        const result = await run(ALL, sources, true);
+        const gate = await run(ALL, sources);
+        const { advanced } = advanceGateMark(EVENT, platformRoot, gate.observed);
         const marks = JSON.parse(readFileSync(watermarkPath(EVENT, platformRoot), "utf-8"));
         expect(marks.mail["ops@example.com|inbox"]).toEqual({ uid: 250, uidValidity: 9 });
         expect(marks.whatsapp.inbound).toBe(1_754_009_999);
@@ -267,75 +279,60 @@ describe("commit", () => {
         expect(marks.lastCommitAt).toMatch(/^\d{4}-\d{2}-\d{2}T/);
         // d1 has no watermark: its answer is a property of the present, not a
         // position in a stream.
-        expect(result.advanced).toEqual(["ops@example.com|inbox", "whatsapp", "calendar"]);
+        expect(advanced).toEqual(["ops@example.com|inbox", "whatsapp", "calendar"]);
+    });
+    it("names the position it wrote per advanced key", async () => {
+        const gate = await run([{ type: "calendar", connector: "google" }], quietSources({ calendarDigest: async () => "DIGEST-Z" }));
+        const { positions } = advanceGateMark(EVENT, platformRoot, gate.observed);
+        expect(positions).toEqual(["calendar:DIGEST-Z"]);
+    });
+    it("stamps lastCommitAt only when something moved", async () => {
+        // Stamping it on every accepted wake would make `auditGateMarkStalled`,
+        // which counts accepted wakes SINCE this instant, read 0 or 1 for ever — the
+        // check built to catch a mark that stopped moving could then never fire, and
+        // `auditGateWatermarkAge` would go permanently green for the same reason.
+        const { advanced } = advanceGateMark(EVENT, platformRoot, {});
+        expect(advanced).toEqual([]);
+        expect(existsSync(watermarkPath(EVENT, platformRoot))).toBe(false);
     });
-    it("a commit whose sources are quiet still stamps lastCommitAt", async () => {
-        // Otherwise a routine that ran and found nothing would look, to the
-        // watermark-age audit, exactly like one whose commits had stopped.
-        await run(ALL, quietSources(), true);
-        const marks = JSON.parse(readFileSync(watermarkPath(EVENT, platformRoot), "utf-8"));
-        expect(marks.lastCommitAt).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+    it("leaves an existing file untouched when nothing moved", async () => {
+        seedWatermarks({ calendar: { digest: "DIGEST-A" }, lastCommitAt: "2026-08-10T10:00:00.000Z" });
+        const before = readFileSync(watermarkPath(EVENT, platformRoot));
+        advanceGateMark(EVENT, platformRoot, {});
+        expect(readFileSync(watermarkPath(EVENT, platformRoot)).equals(before)).toBe(true);
     });
-    it("a committed watermark makes the next plain call quiet", async () => {
+    it("an advanced watermark makes the next gate call quiet", async () => {
         const sources = quietSources({ calendarDigest: async () => "DIGEST-Z" });
         const checks = [{ type: "calendar", connector: "google" }];
-        expect(await run(checks, sources)).toEqual({ hasWork: true, reasons: ["calendar"] });
-        await run(checks, sources, true);
-        expect(await run(checks, sources)).toEqual({ hasWork: false, reasons: [] });
+        const first = await run(checks, sources);
+        expect(first).toMatchObject({ hasWork: true, reasons: ["calendar"], errored: [] });
+        advanceGateMark(EVENT, platformRoot, first.observed);
+        expect(await run(checks, sources)).toMatchObject({ hasWork: false, reasons: [], errored: [] });
     });
-    it("a check that errors is not committed, so its work is not marked consumed", async () => {
+    it("a check that errored is not advanced, so its work is not marked consumed", async () => {
         const checks = [{ type: "calendar", connector: "google" }];
         const sources = quietSources({
             calendarDigest: async () => {
                 throw new Error("neo4j down");
             },
         });
-        const result = await run(checks, sources, true);
-        expect(result).toMatchObject({ hasWork: true, reasons: ["calendar"], advanced: [] });
-        const marks = JSON.parse(readFileSync(watermarkPath(EVENT, platformRoot), "utf-8"));
-        expect(marks.calendar).toBeUndefined();
-    });
-    // Task 2633 — the agent that raised it read `advanced: []` from a commit over
-    // four d1 checks, inferred a broken watermark, reported an unfixable platform
-    // fault, and deleted all four checks.
-    it("names the checks that hold no watermark, instead of omitting them in silence", async () => {
-        const checks = [
-            { type: "mail", mailbox: "ops@example.com" },
-            { type: "d1", database: "bookings", sql: "SELECT count(*) FROM b" },
-        ];
-        const result = await run(checks, quietSources(), true);
-        // Task 2635 folds the folder segment to lower case on write.
-        expect(result.advanced).toEqual(["ops@example.com|inbox"]);
-        expect(result.skipped).toEqual(["d1"]);
+        const gate = await run(checks, sources);
+        expect(gate).toMatchObject({ hasWork: true, reasons: ["calendar"], observed: {} });
+        const { advanced } = advanceGateMark(EVENT, platformRoot, gate.observed);
+        expect(advanced).toEqual([]);
+        expect(existsSync(watermarkPath(EVENT, platformRoot))).toBe(false);
     });
-    it("counts every skipped check, not every skipped kind", async () => {
-        const checks = [
+    it("a check holding no position contributes no key, so nothing advances for it", async () => {
+        // Task 2633 — an agent read an empty `advanced` over four d1 checks,
+        // inferred a broken watermark and deleted all four. `d1` and `whatsapp` in
+        // `status` scope read a current value; there is no position to record.
+        const gate = await run([
             { type: "d1", database: "bookings", sql: "SELECT max(id) FROM b" },
             { type: "d1", database: "leads", sql: "SELECT max(id) FROM l" },
             { type: "whatsapp", scope: "status" },
-        ];
-        const result = await run(checks, quietSources(), true);
-        expect(result.skipped).toEqual(["d1", "d1", "whatsapp"]);
-    });
-    it("a plain call reports no skipped array at all", async () => {
-        const checks = [
-            { type: "d1", database: "bookings", sql: "SELECT count(*) FROM b" },
-        ];
-        expect(await run(checks, quietSources())).toEqual({ hasWork: false, reasons: [] });
-    });
-    it("a check that errored is neither advanced nor skipped, because its state is unknown", async () => {
-        const checks = [
-            { type: "d1", database: "bookings", sql: "SELECT count(*) FROM b" },
-            { type: "calendar", connector: "google" },
-        ];
-        const sources = quietSources({
-            calendarDigest: async () => {
-                throw new Error("neo4j down");
-            },
-        });
-        const result = await run(checks, sources, true);
-        expect(result.advanced).toEqual([]);
-        expect(result.skipped).toEqual(["d1"]);
+        ], quietSources());
+        expect(gate.observed).toEqual({});
+        expect(advanceGateMark(EVENT, platformRoot, gate.observed).advanced).toEqual([]);
     });
 });
 describe("watermark location", () => {
@@ -586,10 +583,16 @@ describe("watermark folder-case fold", () => {
         const sources = quietSources({
             mail: async (_c, since) => ({ matched: false, highestUid: since + 1, uidValidity: 1 }),
         });
-        const first = await run([lower], sources, true);
-        expect(first.advanced).toEqual(["ops@example.com|inbox"]);
-        const second = await run([upper], sources, true);
-        expect(second.advanced).toEqual(["ops@example.com|inbox"]);
+        // Task 2663 — each advance promotes what its own gate call read, so both
+        // fires run the real two-step sequence.
+        const firstGate = await run([lower], sources);
+        expect(advanceGateMark(EVENT, platformRoot, firstGate.observed).advanced).toEqual([
+            "ops@example.com|inbox",
+        ]);
+        const secondGate = await run([upper], sources);
+        expect(advanceGateMark(EVENT, platformRoot, secondGate.observed).advanced).toEqual([
+            "ops@example.com|inbox",
+        ]);
         const marks = JSON.parse(readFileSync(watermarkPath(EVENT, platformRoot), "utf-8"));
         expect(Object.keys(marks.mail)).toEqual(["ops@example.com|inbox"]);
         // The second call read the first call's position rather than restarting at 0.
@@ -647,21 +650,23 @@ describe("telegram check", () => {
     };
     const measured = (lines) => lines.every((l) => !l.includes("op=check-error"));
     it("is false when the account holds no inbound message at all", async () => {
-        expect(await run([CHECK], quietSources())).toEqual({ hasWork: false, reasons: [] });
+        expect(await run([CHECK], quietSources())).toMatchObject({ hasWork: false, reasons: [], errored: [] });
     });
     it("is false when nothing arrived after the watermark", async () => {
         seedWatermarks({ telegram: { inbound: "2026-08-05T10:00:00.000Z" } });
-        expect(await run([CHECK], quietSources(at("2026-08-05T09:00:00.000Z")))).toEqual({
+        expect(await run([CHECK], quietSources(at("2026-08-05T09:00:00.000Z")))).toMatchObject({
             hasWork: false,
             reasons: [],
+            errored: [],
         });
     });
     it("is true when a message arrived after the watermark", async () => {
         seedWatermarks({ telegram: { inbound: "2026-08-05T10:00:00.000Z" } });
         const lines = linesFrom();
-        expect(await run([CHECK], quietSources(at("2026-08-05T11:00:00.000Z")))).toEqual({
+        expect(await run([CHECK], quietSources(at("2026-08-05T11:00:00.000Z")))).toMatchObject({
             hasWork: true,
             reasons: ["telegram"],
+            errored: [],
         });
         expect(measured(lines)).toBe(true);
     });
@@ -669,16 +674,18 @@ describe("telegram check", () => {
         // The boundary is `>`, not `>=`. A `>=` would re-report the last handled
         // message on every fire and the gate could never go quiet.
         seedWatermarks({ telegram: { inbound: "2026-08-05T10:00:00.000Z" } });
-        expect(await run([CHECK], quietSources(at("2026-08-05T10:00:00.000Z")))).toEqual({
+        expect(await run([CHECK], quietSources(at("2026-08-05T10:00:00.000Z")))).toMatchObject({
             hasWork: false,
             reasons: [],
+            errored: [],
         });
     });
     it("is true on a first run, so nothing already waiting is missed", async () => {
         const lines = linesFrom();
-        expect(await run([CHECK], quietSources(at("2026-08-05T09:00:00.000Z")))).toEqual({
+        expect(await run([CHECK], quietSources(at("2026-08-05T09:00:00.000Z")))).toMatchObject({
             hasWork: true,
             reasons: ["telegram"],
+            errored: [],
         });
         expect(measured(lines)).toBe(true);
     });
@@ -689,7 +696,11 @@ describe("telegram check", () => {
                 throw new Error("HTTP 500 on GET /api/telegram-reader/gate-probe");
             },
         });
-        expect(await run([CHECK], sources)).toEqual({ hasWork: true, reasons: ["telegram"] });
+        expect(await run([CHECK], sources)).toMatchObject({
+            hasWork: true,
+            reasons: ["telegram"],
+            errored: [{ kind: "telegram", detail: "HTTP 500 on GET /api/telegram-reader/gate-probe" }],
+        });
         // The opposite of the two assertions above: this one MUST name the failure,
         // or a permanently broken probe reads as a permanently busy account. The
         // DETAIL is asserted, not just the kind — an unrecognised check type also
@@ -699,20 +710,112 @@ describe("telegram check", () => {
         expect(line).toContain("kind=telegram");
         expect(line).toContain("/api/telegram-reader/gate-probe");
     });
-    it("a commit advances the watermark to what the probe just read", async () => {
-        const result = await run([CHECK], quietSources(at("2026-08-05T11:00:00.000Z")), true);
-        expect(result.advanced).toEqual(["telegram"]);
+    it("the advance writes the watermark to what the gate's probe read", async () => {
+        const gate = await run([CHECK], quietSources(at("2026-08-05T11:00:00.000Z")));
+        expect(advanceGateMark(EVENT, platformRoot, gate.observed).advanced).toEqual(["telegram"]);
         const marks = readWatermarks(EVENT, platformRoot);
         expect(marks.telegram).toEqual({ inbound: "2026-08-05T11:00:00.000Z" });
     });
-    it("a commit on a quiet account is skipped, not advanced onto nothing", async () => {
+    // Task 2662 — the bot scope. Before it the check named no bot and the probe
+    // read every conversation on the account, so a routine watching a booking bot
+    // woke for every message to a relay bot sharing that account. A `botId` on the
+    // check was accepted by the schema and reached nothing that read it.
+    it("forwards botId to the source, so the probe can scope to one bot", async () => {
+        const seen = [];
+        const sources = quietSources({
+            telegramInbound: async (_a, botId) => {
+                seen.push(botId);
+                return { newestInboundAt: null };
+            },
+        });
+        await run([{ type: "telegram", scope: "inbound", botId: "111" }], sources);
+        expect(seen).toEqual(["111"]);
+    });
+    it("calls the source with no botId when the check names none", async () => {
+        // The account-wide shape 2653 shipped. A gate bound before 2660 carries no
+        // botId and must keep answering for the whole account.
+        const seen = [];
+        const sources = quietSources({
+            telegramInbound: async (_a, botId) => {
+                seen.push(botId);
+                return { newestInboundAt: null };
+            },
+        });
+        await run([CHECK], sources);
+        expect(seen).toEqual([undefined]);
+    });
+    it("keeps each bot scope on its own watermark, so narrowing a gate cannot skip work", async () => {
+        // The mail check keys `<mailbox>|<folder>` for this reason (Task 2635): two
+        // scopes sharing one position means the narrower one inherits a mark taken
+        // for a wider set. Here the account-wide mark is LATER than bot 111's own
+        // newest, so a shared key would answer "no work" while 111 holds a message
+        // nobody has read. That is the mute direction, and it loses a booking.
+        seedWatermarks({ telegram: { inbound: "2026-08-05T18:00:00.000Z" } });
+        const check = { type: "telegram", scope: "inbound", botId: "111" };
+        expect(await run([check], quietSources(at("2026-08-05T12:00:00.000Z")))).toMatchObject({
+            hasWork: true,
+            reasons: ["telegram"],
+            errored: [],
+        });
+    });
+    it("a scoped advance writes under the bot, leaving the account-wide mark alone", async () => {
+        seedWatermarks({ telegram: { inbound: "2026-08-05T18:00:00.000Z" } });
+        const check = { type: "telegram", scope: "inbound", botId: "111" };
+        const sources = quietSources(at("2026-08-05T12:00:00.000Z"));
+        const gate = await run([check], sources);
+        expect(advanceGateMark(EVENT, platformRoot, gate.observed).advanced).toEqual(["telegram:111"]);
+        const marks = readWatermarks(EVENT, platformRoot);
+        expect(marks.telegram?.inbound).toBe("2026-08-05T18:00:00.000Z");
+        expect(marks.telegram?.byBot).toEqual({ "111": "2026-08-05T12:00:00.000Z" });
+    });
+    it("two bots on one event hold two positions", async () => {
+        seedWatermarks({
+            telegram: { byBot: { "111": "2026-08-05T12:00:00.000Z", "222": "2026-08-05T20:00:00.000Z" } },
+        });
+        const a = { type: "telegram", scope: "inbound", botId: "111" };
+        const b = { type: "telegram", scope: "inbound", botId: "222" };
+        expect(await run([a], quietSources(at("2026-08-05T13:00:00.000Z")))).toMatchObject({
+            hasWork: true,
+        });
+        expect(await run([b], quietSources(at("2026-08-05T13:00:00.000Z")))).toMatchObject({
+            hasWork: false,
+        });
+    });
+    it("reports work and names the bot when the probe refuses an unknown one", async () => {
+        // The operator's own reproduction: id `0000000000`. The probe answers 404,
+        // which reaches here as an unreadable check. It must report WORK, never
+        // quiet, or the routine is muted for ever with nothing in the log.
+        const lines = linesFrom();
+        const sources = quietSources({
+            telegramInbound: async (_a, botId) => {
+                throw new Error(`HTTP 404 on GET /api/telegram-reader/gate-probe?botId=${botId}`);
+            },
+        });
+        const check = { type: "telegram", scope: "inbound", botId: "0000000000" };
+        const result = await run([check], sources);
+        expect(result).toMatchObject({ hasWork: true, reasons: ["telegram"] });
+        // Task 2658's structured arm carries the reason, so a caller can tell a bot
+        // with messages from a bot id that resolves to nothing. `reasons` alone
+        // cannot: it holds "telegram" either way.
+        expect(result.errored).toEqual([
+            {
+                kind: "telegram",
+                detail: "HTTP 404 on GET /api/telegram-reader/gate-probe?botId=0000000000",
+            },
+        ]);
+        const line = lines.find((l) => l.includes("op=check-error"));
+        expect(line).toContain("kind=telegram");
+        expect(line).toContain("0000000000");
+    });
+    it("a quiet account records no position, so nothing advances onto nothing", async () => {
         // A null probe is "nothing to measure from", not "position zero". There is
-        // no position to record, so the check reports as `skipped` exactly as `d1`
-        // does, and the stored mark is left alone. Writing null would drop the mark
-        // and re-report every stored message on the next fire.
+        // no position to record, so the check contributes no key and the stored mark
+        // is left alone. Writing null would drop the mark and re-report every stored
+        // message on the next fire.
         seedWatermarks({ telegram: { inbound: "2026-08-05T10:00:00.000Z" } });
-        const result = await run([CHECK], quietSources(), true);
-        expect(result).toMatchObject({ hasWork: false, advanced: [], skipped: ["telegram"] });
+        const gate = await run([CHECK], quietSources());
+        expect(gate).toMatchObject({ hasWork: false, observed: {} });
+        expect(advanceGateMark(EVENT, platformRoot, gate.observed).advanced).toEqual([]);
         expect(readWatermarks(EVENT, platformRoot).telegram).toEqual({
             inbound: "2026-08-05T10:00:00.000Z",
         });
@@ -726,7 +829,16 @@ describe("telegram check", () => {
 describe("unrecognised check type", () => {
     const CHECK = { type: "nonsense" };
     it("resolves rather than throwing, and counts the unknown type as work", async () => {
-        expect(await run([CHECK], quietSources())).toEqual({ hasWork: true, reasons: ["nonsense"] });
+        expect(await run([CHECK], quietSources())).toMatchObject({
+            hasWork: true,
+            reasons: ["nonsense"],
+            errored: [
+                {
+                    kind: "nonsense",
+                    detail: 'unknown check type "nonsense" — accepted: mail, d1, whatsapp, calendar, telegram',
+                },
+            ],
+        });
     });
     it("names the type and the accepted set in op=check-error", async () => {
         const lines = [];
@@ -741,7 +853,309 @@ describe("unrecognised check type", () => {
     });
     it("still runs the sibling checks — one bad type does not abort the gate", async () => {
         const checks = [CHECK, { type: "d1", database: "b", sql: "SELECT 1" }];
-        expect(await run(checks, quietSources())).toEqual({ hasWork: true, reasons: ["nonsense"] });
+        expect(await run(checks, quietSources())).toMatchObject({
+            hasWork: true,
+            reasons: ["nonsense"],
+            errored: [
+                {
+                    kind: "nonsense",
+                    detail: 'unknown check type "nonsense" — accepted: mail, d1, whatsapp, calendar, telegram',
+                },
+            ],
+        });
+    });
+});
+// ---------------------------------------------------------------------------
+// Task 2658 — `reasons` carries the check type on the real-work arm and the
+// error arm alike, so `{"hasWork":true,"reasons":["d1"]}` is byte-identical for
+// a database holding rows and one that 403s. `errored` is the only place that
+// difference survives the call, and no bind-time guard is writable without it.
+// ---------------------------------------------------------------------------
+describe("errored", () => {
+    const D1 = { type: "d1", database: "db", sql: "SELECT 1" };
+    it("is empty when every check answers", async () => {
+        const res = await run([D1], quietSources());
+        expect(res.errored).toEqual([]);
+    });
+    it("names the kind and the source's own message when a check throws", async () => {
+        const sources = quietSources({
+            d1: async () => {
+                throw new Error("HTTP 403 on POST /api/storage/d1/query");
+            },
+        });
+        const res = await run([D1], sources);
+        expect(res.errored).toEqual([{ kind: "d1", detail: "HTTP 403 on POST /api/storage/d1/query" }]);
+    });
+    it("is not distinguishable from a real hit by hasWork or reasons alone", async () => {
+        const thrown = await run([D1], quietSources({
+            d1: async () => {
+                throw new Error("HTTP 403 on POST /api/storage/d1/query");
+            },
+        }));
+        const real = await run([D1], quietSources({ d1: async () => 7 }));
+        expect(thrown.hasWork).toBe(real.hasWork);
+        expect(thrown.reasons).toEqual(real.reasons);
+        expect(thrown.errored).toHaveLength(1);
+        expect(real.errored).toEqual([]);
+    });
+    it("carries one entry per erroring check, in checks order", async () => {
+        const sources = quietSources({
+            d1: async () => {
+                throw new Error("d1 down");
+            },
+            calendarDigest: async () => {
+                throw new Error("calendar down");
+            },
+        });
+        const checks = [
+            D1,
+            { type: "whatsapp", scope: "status" },
+            { type: "calendar", connector: "google" },
+        ];
+        const res = await run(checks, sources);
+        expect(res.errored).toEqual([
+            { kind: "d1", detail: "d1 down" },
+            { kind: "calendar", detail: "calendar down" },
+        ]);
+    });
+    it("is present and empty when every check answered", async () => {
+        const res = await run([D1], quietSources());
+        expect(res.errored).toEqual([]);
+    });
+});
+// Task 2657 — the same check, on a mailbox the outlook plugin holds.
+//
+// The first test is the one that matters. Graph's
+// `$top=1&$orderby=receivedDateTime desc` returns the newest message whether or
+// not anything arrived, exactly as `UID SEARCH n+1:*` returns the last message
+// above the highest UID — so an implementation that reports work on any
+// non-empty response passes every other test here, which is how Task 2471
+// shipped.
+describe("mail check — outlook provider", () => {
+    const CHECK = { type: "mail", mailbox: "admin@muvin.co.uk", provider: "outlook" };
+    const KEY = "admin@muvin.co.uk|inbox";
+    it("is false when the newest message equals the watermark", async () => {
+        seedWatermarks({ mailOutlook: { [KEY]: { receivedAt: "2026-08-10T09:00:00Z" } } });
+        const sources = quietSources({
+            mailOutlook: async () => ({ newestReceivedAt: "2026-08-10T09:00:00Z" }),
+        });
+        expect(await run([CHECK], sources)).toMatchObject({ hasWork: false, reasons: [], errored: [] });
+    });
+    it("is true on a message above the watermark, and the advance writes that key", async () => {
+        seedWatermarks({ mailOutlook: { [KEY]: { receivedAt: "2026-08-10T09:00:00Z" } } });
+        const sources = quietSources({
+            mailOutlook: async () => ({ newestReceivedAt: "2026-08-10T09:05:00Z" }),
+        });
+        const gate = await run([CHECK], sources);
+        expect(gate).toMatchObject({ hasWork: true, reasons: ["mail"], errored: [] });
+        expect(advanceGateMark(EVENT, platformRoot, gate.observed).advanced).toEqual([KEY]);
+        const written = JSON.parse(readFileSync(watermarkPath(EVENT, platformRoot), "utf-8"));
+        expect(written.mailOutlook[KEY]).toEqual({ receivedAt: "2026-08-10T09:05:00Z" });
+    });
+    it("is true on a first run, when nothing is stored", async () => {
+        const sources = quietSources({
+            mailOutlook: async () => ({ newestReceivedAt: "2026-08-10T09:00:00Z" }),
+        });
+        expect(await run([CHECK], sources)).toMatchObject({ hasWork: true, reasons: ["mail"], errored: [] });
+    });
+    it("orders by instant, not lexically, so a fractional second is not read as older", async () => {
+        seedWatermarks({ mailOutlook: { [KEY]: { receivedAt: "2026-08-10T09:00:00Z" } } });
+        const sources = quietSources({
+            // Lexically "…00.500Z" sorts BELOW "…00Z" ('.' is 0x2E, 'Z' is 0x5A).
+            mailOutlook: async () => ({ newestReceivedAt: "2026-08-10T09:00:00.500Z" }),
+        });
+        expect(await run([CHECK], sources)).toMatchObject({ hasWork: true, reasons: ["mail"], errored: [] });
+    });
+    it("records no position for an empty folder rather than advancing onto nothing", async () => {
+        const sources = quietSources({ mailOutlook: async () => ({ newestReceivedAt: null }) });
+        const gate = await run([CHECK], sources);
+        expect(gate).toEqual({ hasWork: false, reasons: [], errored: [], observed: {} });
+        expect(advanceGateMark(EVENT, platformRoot, gate.observed).advanced).toEqual([]);
+    });
+    it("keys the folder segment lower-cased, so two spellings address one entry", async () => {
+        seedWatermarks({ mailOutlook: { [KEY]: { receivedAt: "2026-08-10T09:00:00Z" } } });
+        const check = { ...CHECK, folder: "Inbox" };
+        const sources = quietSources({
+            mailOutlook: async () => ({ newestReceivedAt: "2026-08-10T09:00:00Z" }),
+        });
+        expect(await run([check], sources)).toMatchObject({ hasWork: false, reasons: [], errored: [] });
+    });
+    it("counts a probe that throws as work, and never as quiet", async () => {
+        const sources = quietSources({
+            mailOutlook: async () => {
+                throw new Error("No Outlook mailbox admin@muvin.co.uk is connected");
+            },
+        });
+        expect(await run([CHECK], sources)).toMatchObject({
+            hasWork: true,
+            reasons: ["mail"],
+            errored: [{ kind: "mail", detail: "No Outlook mailbox admin@muvin.co.uk is connected" }],
+        });
+    });
+    it("throws on a provider outside the accepted list", async () => {
+        const check = { type: "mail", mailbox: "a@b.com", provider: "pop3" };
+        expect(await run([check], quietSources())).toMatchObject({
+            hasWork: true,
+            reasons: ["mail"],
+            errored: [{ kind: "mail", detail: 'unknown mail provider "pop3" — accepted: imap, outlook' }],
+        });
+    });
+    it("leaves the IMAP watermark map untouched", async () => {
+        seedWatermarks({ mail: { [KEY]: { uid: 42, uidValidity: 7 } } });
+        const sources = quietSources({
+            mailOutlook: async () => ({ newestReceivedAt: "2026-08-10T09:00:00Z" }),
+        });
+        // Task 2663 — the gate call records the position the advance promotes.
+        const gate = await run([CHECK], sources);
+        advanceGateMark(EVENT, platformRoot, gate.observed);
+        const written = JSON.parse(readFileSync(watermarkPath(EVENT, platformRoot), "utf-8"));
+        expect(written.mail[KEY]).toEqual({ uid: 42, uidValidity: 7 });
+        expect(written.mailOutlook[KEY]).toEqual({ receivedAt: "2026-08-10T09:00:00Z" });
+    });
+    it("takes the IMAP arm when provider is absent", async () => {
+        let outlookCalled = false;
+        const sources = quietSources({
+            mailOutlook: async () => {
+                outlookCalled = true;
+                return { newestReceivedAt: "2026-08-10T09:00:00Z" };
+            },
+        });
+        await run([{ type: "mail", mailbox: "admin@muvin.co.uk" }], sources);
+        expect(outlookCalled).toBe(false);
+    });
+});
+// ---------------------------------------------------------------------------
+// Task 2654, kept under Task 2663 — a source that moves between the gate call
+// and the advance.
+//
+// The advance happens after the wake was accepted, by which time the source may
+// have moved again. Writing what the source holds THEN would put the arrival
+// below the mark and no later fire would report it. The dispatcher writes what
+// the GATE returned instead, so the mover stays above. Under 2654 that guarantee
+// depended on a sidecar file being fresh; it is now structural, because the
+// positions travel with the result.
+//
+// Each check is driven alone, and each test runs the real sequence: gate, source
+// moves, advance, gate again.
+// ---------------------------------------------------------------------------
+describe("a source that moves between the gate call and the advance", () => {
+    it("mail: a UID that arrives mid-turn is still reported after the advance", async () => {
+        let highest = 105;
+        const sources = quietSources({
+            mail: async (_c, sinceUid) => ({
+                matched: highest > sinceUid,
+                highestUid: Math.max(highest, sinceUid),
+                uidValidity: 1,
+            }),
+        });
+        const checks = [{ type: "mail", mailbox: "ops@example.com" }];
+        const gate = await run(checks, sources);
+        expect(gate).toMatchObject({ hasWork: true, reasons: ["mail"], errored: [] });
+        highest = 106; // arrives while the turn runs
+        advanceGateMark(EVENT, platformRoot, gate.observed);
+        const marks = JSON.parse(readFileSync(watermarkPath(EVENT, platformRoot), "utf-8"));
+        expect(marks.mail["ops@example.com|inbox"].uid).toBe(105);
+        expect(await run(checks, sources)).toMatchObject({ hasWork: true, reasons: ["mail"] });
+    });
+    it("whatsapp: an inbound message mid-turn is still reported after the advance", async () => {
+        let latest = 1_754_000_100;
+        const sources = quietSources({
+            whatsappInbound: async (_a, since) => ({
+                latest: Math.max(latest, since),
+                newer: latest > since,
+            }),
+        });
+        const checks = [{ type: "whatsapp", scope: "inbound" }];
+        const gate = await run(checks, sources);
+        expect(gate).toMatchObject({ hasWork: true, reasons: ["whatsapp"], errored: [] });
+        latest = 1_754_000_200;
+        advanceGateMark(EVENT, platformRoot, gate.observed);
+        const marks = JSON.parse(readFileSync(watermarkPath(EVENT, platformRoot), "utf-8"));
+        expect(marks.whatsapp.inbound).toBe(1_754_000_100);
+        expect(await run(checks, sources)).toMatchObject({ hasWork: true, reasons: ["whatsapp"] });
+    });
+    it("telegram: an inbound message mid-turn is still reported after the advance", async () => {
+        let newest = "2026-08-10T10:00:00.000Z";
+        const sources = quietSources({ telegramInbound: async () => ({ newestInboundAt: newest }) });
+        const checks = [{ type: "telegram", scope: "inbound" }];
+        const gate = await run(checks, sources);
+        expect(gate).toMatchObject({ hasWork: true, reasons: ["telegram"], errored: [] });
+        newest = "2026-08-10T10:30:00.000Z";
+        advanceGateMark(EVENT, platformRoot, gate.observed);
+        const marks = JSON.parse(readFileSync(watermarkPath(EVENT, platformRoot), "utf-8"));
+        expect(marks.telegram.inbound).toBe("2026-08-10T10:00:00.000Z");
+        expect(await run(checks, sources)).toMatchObject({ hasWork: true, reasons: ["telegram"] });
+    });
+    it("calendar: a connector change mid-turn is still reported after the advance", async () => {
+        let digest = "DIGEST-A";
+        const sources = quietSources({ calendarDigest: async () => digest });
+        const checks = [{ type: "calendar", connector: "google" }];
+        const gate = await run(checks, sources);
+        expect(gate).toMatchObject({ hasWork: true, reasons: ["calendar"], errored: [] });
+        digest = "DIGEST-B";
+        advanceGateMark(EVENT, platformRoot, gate.observed);
+        const marks = JSON.parse(readFileSync(watermarkPath(EVENT, platformRoot), "utf-8"));
+        expect(marks.calendar.digest).toBe("DIGEST-A");
+        expect(await run(checks, sources)).toMatchObject({ hasWork: true, reasons: ["calendar"] });
+    });
+    // Task 2663 — the no-event case. The gate that could never go quiet emitted a
+    // line on every fire that looked exactly like a healthy one, because it named
+    // only what the probe had just read and never the value it was compared
+    // against. Both sides now print, so a mark stuck on an empty slot is legible
+    // from one line without reproducing anything.
+    describe("gate-read names both sides of the comparison", () => {
+        // `console.error` is already spied in `beforeEach`, so its recorded calls are
+        // the log. Re-mocking it here would drop the lines written before this point.
+        const errorLines = () => vi.mocked(console.error).mock.calls.map((c) => c.map(String).join(" "));
+        it("names null stored on a first fire, and the observed position beside it", async () => {
+            const sources = quietSources({ calendarDigest: async () => "abcdef0123456789" });
+            await run([{ type: "calendar", connector: "google" }], sources);
+            expect(errorLines()).toContainEqual(expect.stringContaining("op=gate-read eventId=65ef758c check=calendar stored=null observed=abcdef01"));
+        });
+        it("names the stored position once the mark has advanced", async () => {
+            const sources = quietSources({ calendarDigest: async () => "abcdef0123456789" });
+            const checks = [{ type: "calendar", connector: "google" }];
+            const gate = await run(checks, sources);
+            advanceGateMark(EVENT, platformRoot, gate.observed);
+            await run(checks, sources);
+            expect(errorLines()).toContainEqual(expect.stringContaining("op=gate-read eventId=65ef758c check=calendar stored=abcdef01 observed=abcdef01"));
+        });
+        it("emits no gate-read for a check that holds no position", async () => {
+            // `op=check-error` already covers a check with no position; a line of two
+            // nulls would only add a value nobody can compare.
+            await run([{ type: "d1", database: "b", sql: "SELECT count(*) FROM b" }], quietSources());
+            expect(errorLines().filter((l) => l.includes("op=gate-read"))).toEqual([]);
+        });
+    });
+});
+// Task 2663 — the gate hands its readings back to the dispatcher and touches no
+// sidecar. The commit and the `<eventId>.observed.json` file it promoted from
+// are both gone: a sidecar survives a gate call that errored, so the stale
+// positions from an earlier fire would be promoted on the next accepted wake and
+// mark as seen messages nobody read.
+describe("observed positions (Task 2663)", () => {
+    it("returns the positions it read, and writes no sidecar", async () => {
+        const result = await run([{ type: "telegram", scope: "inbound", botId: "555" }], quietSources({ telegramInbound: async () => ({ newestInboundAt: "2026-08-10T18:00:00.000Z" }) }));
+        expect(result.observed).toEqual({ telegram: { byBot: { "555": "2026-08-10T18:00:00.000Z" } } });
+        expect(existsSync(join(platformRoot, "..", "state", "scheduling-gate", `${EVENT}.observed.json`))).toBe(false);
+    });
+    it("reports no position for a check that holds none", async () => {
+        // `d1` reads a current value rather than a position in a stream, so there is
+        // nothing for the dispatcher to promote and `observed` is empty rather than
+        // carrying a fabricated key.
+        const result = await run([{ type: "d1", database: "b", sql: "SELECT 1" }], quietSources({ d1: async () => 1 }));
+        expect(result.observed).toEqual({});
+    });
+    it("reports no position for a check that threw", async () => {
+        // A check that errored knows nothing about its source. Recording a position
+        // for it would let the dispatcher advance past work the gate never saw.
+        const result = await run([{ type: "telegram", scope: "inbound", botId: "555" }], quietSources({
+            telegramInbound: async () => {
+                throw new Error("fetch failed");
+            },
+        }));
+        expect(result.hasWork).toBe(true);
+        expect(result.observed).toEqual({});
     });
 });
 //# sourceMappingURL=scheduling-gate.test.js.map