@rubytech/create-realagent-code 0.1.590 → 0.1.591

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, watermarkPath, observationPath, 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,
     };
 }
@@ -60,12 +62,13 @@ const run = (checks, sources, commit = false) => runSchedulingGate({ eventId: EV
 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())).toEqual({ hasWork: false, reasons: [], errored: [] });
     });
     it("is true on one row", async () => {
         expect(await run([CHECK], quietSources({ d1: async () => 1 }))).toEqual({
             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)).toEqual({
+            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())).toEqual({ 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)).toEqual({ 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)).toEqual({ 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())).toEqual({ 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)).toEqual({ 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)).toEqual({ 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())).toEqual({ 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)).toEqual({ 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())).toEqual({ hasWork: true, reasons: ["calendar"], errored: [] });
     });
 });
 describe("digestBusy", () => {
@@ -222,7 +229,7 @@ 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())).toEqual({ hasWork: false, reasons: [], errored: [] });
     });
     it("one noisy source is enough, and names only itself", async () => {
         seedWatermarks({
@@ -232,6 +239,7 @@ describe("all four together", () => {
         expect(await run(ALL, quietSources({ d1: async () => 2 }))).toEqual({
             hasWork: true,
             reasons: ["d1"],
+            errored: [],
         });
     });
 });
@@ -259,6 +267,9 @@ describe("commit", () => {
             whatsappInbound: async () => ({ latest: 1_754_009_999, newer: true }),
             calendarDigest: async () => "DIGEST-Z",
         });
+        // Task 2654 — the commit promotes what the gate read, so the gate call is
+        // part of the sequence. A bare commit advances nothing, by design.
+        await run(ALL, sources);
         const result = await run(ALL, sources, true);
         const marks = JSON.parse(readFileSync(watermarkPath(EVENT, platformRoot), "utf-8"));
         expect(marks.mail["ops@example.com|inbox"]).toEqual({ uid: 250, uidValidity: 9 });
@@ -279,9 +290,9 @@ describe("commit", () => {
     it("a committed watermark makes the next plain 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"] });
+        expect(await run(checks, sources)).toEqual({ hasWork: true, reasons: ["calendar"], errored: [] });
         await run(checks, sources, true);
-        expect(await run(checks, sources)).toEqual({ hasWork: false, reasons: [] });
+        expect(await run(checks, sources)).toEqual({ hasWork: false, reasons: [], errored: [] });
     });
     it("a check that errors is not committed, so its work is not marked consumed", async () => {
         const checks = [{ type: "calendar", connector: "google" }];
@@ -303,6 +314,8 @@ describe("commit", () => {
             { type: "mail", mailbox: "ops@example.com" },
             { type: "d1", database: "bookings", sql: "SELECT count(*) FROM b" },
         ];
+        // Task 2654 — the gate call records the position the commit promotes.
+        await run(checks, quietSources());
         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"]);
@@ -321,7 +334,7 @@ describe("commit", () => {
         const checks = [
             { type: "d1", database: "bookings", sql: "SELECT count(*) FROM b" },
         ];
-        expect(await run(checks, quietSources())).toEqual({ hasWork: false, reasons: [] });
+        expect(await run(checks, quietSources())).toEqual({ hasWork: false, reasons: [], errored: [] });
     });
     it("a check that errored is neither advanced nor skipped, because its state is unknown", async () => {
         const checks = [
@@ -586,8 +599,12 @@ describe("watermark folder-case fold", () => {
         const sources = quietSources({
             mail: async (_c, since) => ({ matched: false, highestUid: since + 1, uidValidity: 1 }),
         });
+        // Task 2654 — each commit promotes what its own gate call read, so both
+        // fires run the real two-step sequence.
+        await run([lower], sources);
         const first = await run([lower], sources, true);
         expect(first.advanced).toEqual(["ops@example.com|inbox"]);
+        await run([upper], sources);
         const second = await run([upper], sources, true);
         expect(second.advanced).toEqual(["ops@example.com|inbox"]);
         const marks = JSON.parse(readFileSync(watermarkPath(EVENT, platformRoot), "utf-8"));
@@ -647,13 +664,14 @@ 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())).toEqual({ 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({
             hasWork: false,
             reasons: [],
+            errored: [],
         });
     });
     it("is true when a message arrived after the watermark", async () => {
@@ -662,6 +680,7 @@ describe("telegram check", () => {
         expect(await run([CHECK], quietSources(at("2026-08-05T11:00:00.000Z")))).toEqual({
             hasWork: true,
             reasons: ["telegram"],
+            errored: [],
         });
         expect(measured(lines)).toBe(true);
     });
@@ -672,6 +691,7 @@ describe("telegram check", () => {
         expect(await run([CHECK], quietSources(at("2026-08-05T10:00:00.000Z")))).toEqual({
             hasWork: false,
             reasons: [],
+            errored: [],
         });
     });
     it("is true on a first run, so nothing already waiting is missed", async () => {
@@ -679,6 +699,7 @@ describe("telegram check", () => {
         expect(await run([CHECK], quietSources(at("2026-08-05T09:00:00.000Z")))).toEqual({
             hasWork: true,
             reasons: ["telegram"],
+            errored: [],
         });
         expect(measured(lines)).toBe(true);
     });
@@ -689,7 +710,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)).toEqual({
+            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,12 +724,110 @@ 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 () => {
+    it("a commit advances the watermark to what the gate's probe read", async () => {
+        // Task 2654 — the gate's probe, not the commit's. The commit runs at the end
+        // of the turn, so its own reading already includes anything that arrived
+        // while the turn ran.
+        await run([CHECK], quietSources(at("2026-08-05T11:00:00.000Z")));
         const result = await run([CHECK], quietSources(at("2026-08-05T11:00:00.000Z")), true);
         expect(result.advanced).toEqual(["telegram"]);
         const marks = readWatermarks(EVENT, platformRoot);
         expect(marks.telegram).toEqual({ inbound: "2026-08-05T11:00:00.000Z" });
     });
+    // 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")))).toEqual({
+            hasWork: true,
+            reasons: ["telegram"],
+            errored: [],
+        });
+    });
+    it("a scoped commit 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"));
+        // Task 2654 — the commit promotes what the GATE read, so the gate call is
+        // part of the sequence. A bare commit advances nothing, by design.
+        await run([check], sources);
+        const result = await run([check], sources, true);
+        expect(result.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 commit on a quiet account is skipped, not advanced 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`
@@ -726,7 +849,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())).toEqual({
+            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 +873,306 @@ 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())).toEqual({
+            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 on a commit too", async () => {
+        const res = await run([D1], quietSources(), true);
+        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)).toEqual({ hasWork: false, reasons: [], errored: [] });
+    });
+    it("is true on a message above the watermark, and advances that key on commit", async () => {
+        seedWatermarks({ mailOutlook: { [KEY]: { receivedAt: "2026-08-10T09:00:00Z" } } });
+        const sources = quietSources({
+            mailOutlook: async () => ({ newestReceivedAt: "2026-08-10T09:05:00Z" }),
+        });
+        // Task 2654 — the commit promotes what the gate read, so the gate call is
+        // part of the sequence. A bare commit advances nothing, by design.
+        await run([CHECK], sources);
+        expect(await run([CHECK], sources, true)).toEqual({
+            hasWork: true,
+            reasons: ["mail"],
+            errored: [],
+            advanced: [KEY],
+            skipped: [],
+        });
+        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)).toEqual({ 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)).toEqual({ hasWork: true, reasons: ["mail"], errored: [] });
+    });
+    it("reports an empty folder as skipped on a commit rather than advancing onto nothing", async () => {
+        const sources = quietSources({ mailOutlook: async () => ({ newestReceivedAt: null }) });
+        expect(await run([CHECK], sources, true)).toEqual({
+            hasWork: false,
+            reasons: [],
+            errored: [],
+            advanced: [],
+            skipped: ["mail"],
+        });
+    });
+    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)).toEqual({ 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)).toEqual({
+            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())).toEqual({
+            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 2654 — the gate call records the position the commit promotes.
+        await run([CHECK], sources);
+        await run([CHECK], sources, true);
+        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 — a source that moves between the gate call and the commit.
+//
+// The commit runs at the END of the agent turn, so its own probe already
+// includes whatever arrived while the turn ran. Writing that position puts the
+// arrival BELOW the watermark and no later fire reports it. The commit writes
+// what the GATE read instead, so the mover stays above.
+//
+// Each check is driven alone, and each test runs the real sequence: gate,
+// source moves, commit, gate again.
+// ---------------------------------------------------------------------------
+describe("a source that moves between the gate call and the commit", () => {
+    it("mail: a UID that arrives mid-turn is still reported after the commit", 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" }];
+        expect(await run(checks, sources)).toEqual({ hasWork: true, reasons: ["mail"], errored: [] });
+        highest = 106; // arrives while the turn runs
+        await run(checks, sources, true);
+        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)).toEqual({ hasWork: true, reasons: ["mail"], errored: [] });
+    });
+    it("whatsapp: an inbound message mid-turn is still reported after the commit", 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" }];
+        expect(await run(checks, sources)).toEqual({ hasWork: true, reasons: ["whatsapp"], errored: [] });
+        latest = 1_754_000_200;
+        await run(checks, sources, true);
+        const marks = JSON.parse(readFileSync(watermarkPath(EVENT, platformRoot), "utf-8"));
+        expect(marks.whatsapp.inbound).toBe(1_754_000_100);
+        expect(await run(checks, sources)).toEqual({ hasWork: true, reasons: ["whatsapp"], errored: [] });
+    });
+    it("telegram: an inbound message mid-turn is still reported after the commit", async () => {
+        let newest = "2026-08-10T10:00:00.000Z";
+        const sources = quietSources({ telegramInbound: async () => ({ newestInboundAt: newest }) });
+        const checks = [{ type: "telegram", scope: "inbound" }];
+        expect(await run(checks, sources)).toEqual({ hasWork: true, reasons: ["telegram"], errored: [] });
+        newest = "2026-08-10T10:30:00.000Z";
+        await run(checks, sources, true);
+        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)).toEqual({ hasWork: true, reasons: ["telegram"], errored: [] });
+    });
+    it("calendar: a connector change mid-turn is still reported after the commit", async () => {
+        let digest = "DIGEST-A";
+        const sources = quietSources({ calendarDigest: async () => digest });
+        const checks = [{ type: "calendar", connector: "google" }];
+        expect(await run(checks, sources)).toEqual({ hasWork: true, reasons: ["calendar"], errored: [] });
+        digest = "DIGEST-B";
+        await run(checks, sources, true);
+        const marks = JSON.parse(readFileSync(watermarkPath(EVENT, platformRoot), "utf-8"));
+        expect(marks.calendar.digest).toBe("DIGEST-A");
+        expect(await run(checks, sources)).toEqual({ hasWork: true, reasons: ["calendar"], errored: [] });
+    });
+    // Task 2654 — the no-event case. A message swallowed in production emitted
+    // nothing at all, and re-running the gate reproduced nothing, so the pair below
+    // is the only way to see a watermark that jumped past an unseen window.
+    describe("gate-read and commit positions pair on one fire", () => {
+        // `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 the position read at gate time and the position written at commit time", async () => {
+            const sources = quietSources({ calendarDigest: async () => "abcdef0123456789" });
+            const checks = [{ type: "calendar", connector: "google" }];
+            await run(checks, sources);
+            await run(checks, sources, true);
+            expect(errorLines()).toContainEqual(expect.stringContaining("op=gate-read eventId=65ef758c check=calendar position=abcdef01"));
+            expect(errorLines()).toContainEqual(expect.stringContaining("positions=calendar:abcdef01"));
+        });
+        it("names an unreadable observation, which otherwise reads as a first commit", async () => {
+            // A present-but-unusable file stops every watermark advancing while
+            // `op=commit` still prints an empty `advanced=` — indistinguishable from a
+            // healthy first commit without a line of its own.
+            const sources = quietSources({ calendarDigest: async () => "DIGEST-Z" });
+            const checks = [{ type: "calendar", connector: "google" }];
+            await run(checks, sources);
+            writeFileSync(observationPath(EVENT, platformRoot), "{ not json");
+            const result = await run(checks, sources, true);
+            expect(result.advanced).toEqual([]);
+            expect(errorLines()).toContainEqual(expect.stringContaining("op=observation-unreadable eventId=65ef758c reason="));
+        });
+        it("says nothing when no observation file exists, which is a first fire", async () => {
+            const sources = quietSources({ calendarDigest: async () => "DIGEST-Z" });
+            await run([{ type: "calendar", connector: "google" }], sources, true);
+            expect(errorLines().filter((l) => l.includes("op=observation-unreadable"))).toEqual([]);
+        });
+        it("emits no gate-read for a check that holds no position", async () => {
+            // `op=check-error` and `skipped=` already cover a check with no position;
+            // a `position=null` line 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([]);
+        });
+    });
+    it("a commit with no gate call before it advances nothing", async () => {
+        // Route two (PLUGIN.md) lets a separate action event issue the commit. With
+        // no observation on file there is no position anyone saw, so the watermark
+        // stays put and the next fire reports the work again — the fail-open
+        // direction the whole tool holds to.
+        const sources = quietSources({ calendarDigest: async () => "DIGEST-Z" });
+        const checks = [{ type: "calendar", connector: "google" }];
+        const result = await run(checks, sources, true);
+        expect(result.advanced).toEqual([]);
+        const marks = JSON.parse(readFileSync(watermarkPath(EVENT, platformRoot), "utf-8"));
+        expect(marks.calendar).toBeUndefined();
+        expect(await run(checks, sources)).toEqual({ hasWork: true, reasons: ["calendar"], errored: [] });
     });
 });
 //# sourceMappingURL=scheduling-gate.test.js.map