switchroom 0.15.45 → 0.16.4

package/telegram-plugin/tests/fleet-fallback-resume.test.ts

@@ -0,0 +1,197 @@
+/**
+ * Unit tests for the resume-after-swap gate (auth-failover-stall Fix 1).
+ *
+ * The gate owns the decision the gateway consults in doFireFleetAutoFallback
+ * after a SUCCESSFUL swap: should we restart to resume the turn the mid-turn
+ * 429 killed? It must:
+ *   - return 'resume' on the first switched outcome (so exactly one restart
+ *     fires), recorded so a follow-on swap is suppressed;
+ *   - return 'skip-inflight' on a SECOND swap within the single-flight window
+ *     (a 429 storm cannot loop-restart the agent);
+ *   - return 'skip-stale' when the failed turn is older than maxAgeMs (an
+ *     ancient interrupted turn is not resurrected);
+ *   - never be consulted on all-blocked (verified by the gateway-seam test
+ *     below, which only calls decide() on 'switched').
+ *
+ * The gate is pure (no process restart), so these tests run with a fake clock
+ * and never touch a real process — the restart itself is a separate seam
+ * (triggerSelfRestart) that the gateway wires to a 'resume' verdict.
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  createFleetFallbackResumeGate,
+  DEFAULT_RESUME_MAX_AGE_MS,
+  DEFAULT_RESUME_SINGLE_FLIGHT_MS,
+} from '../fleet-fallback-resume.js'
+
+function fakeClock(start = 1_000_000) {
+  let t = start
+  return {
+    now: () => t,
+    advance: (ms: number) => {
+      t += ms
+    },
+    set: (ms: number) => {
+      t = ms
+    },
+  }
+}
+
+describe('createFleetFallbackResumeGate — resume verdict', () => {
+  it("returns 'resume' on the first switched outcome", () => {
+    const clk = fakeClock()
+    const gate = createFleetFallbackResumeGate({ nowFn: clk.now })
+    // Failed turn started just now → fresh, not stale.
+    expect(gate.decide(clk.now())).toBe('resume')
+  })
+
+  it("treats a null (unknown) failed-turn timestamp as resumable", () => {
+    const clk = fakeClock()
+    const gate = createFleetFallbackResumeGate({ nowFn: clk.now })
+    // null defers staleness to the boot-resume 3h failsafe → resume here.
+    expect(gate.decide(null)).toBe('resume')
+  })
+})
+
+describe('createFleetFallbackResumeGate — single-flight guard', () => {
+  it('suppresses a SECOND swap inside the single-flight window (no double-resume)', () => {
+    const clk = fakeClock()
+    const gate = createFleetFallbackResumeGate({
+      nowFn: clk.now,
+      singleFlightMs: DEFAULT_RESUME_SINGLE_FLIGHT_MS,
+    })
+    expect(gate.decide(clk.now())).toBe('resume')
+    // A 429 storm: a second swap fires 1s later. Must NOT re-arm.
+    clk.advance(1_000)
+    expect(gate.decide(clk.now())).toBe('skip-inflight')
+    // Still suppressed near the end of the window.
+    clk.advance(DEFAULT_RESUME_SINGLE_FLIGHT_MS - 2_000)
+    expect(gate.decide(clk.now())).toBe('skip-inflight')
+  })
+
+  it('re-arms once the single-flight window has fully elapsed', () => {
+    const clk = fakeClock()
+    const gate = createFleetFallbackResumeGate({ nowFn: clk.now, singleFlightMs: 60_000 })
+    expect(gate.decide(clk.now())).toBe('resume')
+    clk.advance(60_001)
+    // A genuinely new swap after the window resumes again (one per swap).
+    expect(gate.decide(clk.now())).toBe('resume')
+  })
+
+  it('a rapid burst of N swaps yields exactly ONE resume', () => {
+    const clk = fakeClock()
+    const gate = createFleetFallbackResumeGate({ nowFn: clk.now, singleFlightMs: 60_000 })
+    let resumes = 0
+    for (let i = 0; i < 10; i++) {
+      if (gate.decide(clk.now()) === 'resume') resumes++
+      clk.advance(500) // 0.5s between storm events, all inside the window
+    }
+    expect(resumes).toBe(1)
+  })
+})
+
+describe('createFleetFallbackResumeGate — staleness guard', () => {
+  it("suppresses ('skip-stale') a failed turn older than maxAgeMs", () => {
+    const clk = fakeClock()
+    const gate = createFleetFallbackResumeGate({ nowFn: clk.now })
+    const ancientStart = clk.now() - (DEFAULT_RESUME_MAX_AGE_MS + 60_000)
+    expect(gate.decide(ancientStart)).toBe('skip-stale')
+  })
+
+  it('a stale verdict does NOT arm the single-flight window', () => {
+    const clk = fakeClock()
+    const gate = createFleetFallbackResumeGate({ nowFn: clk.now })
+    expect(gate.decide(clk.now() - (DEFAULT_RESUME_MAX_AGE_MS + 1))).toBe('skip-stale')
+    // A subsequent FRESH turn must still resume — the stale skip must not have
+    // recorded an arm time.
+    expect(gate.decide(clk.now())).toBe('resume')
+  })
+
+  it('a turn just under maxAgeMs still resumes', () => {
+    const clk = fakeClock()
+    const gate = createFleetFallbackResumeGate({ nowFn: clk.now, maxAgeMs: 10_800_000 })
+    expect(gate.decide(clk.now() - (10_800_000 - 1_000))).toBe('resume')
+  })
+
+  it('honours a custom maxAgeMs', () => {
+    const clk = fakeClock()
+    const gate = createFleetFallbackResumeGate({ nowFn: clk.now, maxAgeMs: 60_000 })
+    expect(gate.decide(clk.now() - 61_000)).toBe('skip-stale')
+    expect(gate.decide(clk.now() - 30_000)).toBe('resume')
+  })
+})
+
+describe('createFleetFallbackResumeGate — reset / inspect seams', () => {
+  it('reset() clears the single-flight arm', () => {
+    const clk = fakeClock()
+    const gate = createFleetFallbackResumeGate({ nowFn: clk.now })
+    expect(gate.decide(clk.now())).toBe('resume')
+    expect(gate.decide(clk.now())).toBe('skip-inflight')
+    gate.reset()
+    expect(gate.inspect().lastResumedAtMs).toBe(Number.NEGATIVE_INFINITY)
+    expect(gate.decide(clk.now())).toBe('resume')
+  })
+})
+
+/**
+ * Gateway-seam contract test. Mirrors how doFireFleetAutoFallback consults the
+ * gate: it calls decide() ONLY on outcome.kind === 'switched', and translates a
+ * 'resume' verdict into exactly one restart. We mock the restart as a counter,
+ * so no process is touched. This pins the "all-blocked is a no-op" and
+ * "exactly-once" contracts at the call-site shape.
+ */
+describe('gateway seam — decide() consulted only on switched, restart fires once', () => {
+  type Outcome = { kind: 'switched' | 'all-blocked' }
+
+  function simulateDispatch(
+    gate: ReturnType<typeof createFleetFallbackResumeGate>,
+    outcome: Outcome,
+    failedTurnStartedAtMs: number | null,
+    restart: () => void,
+  ): void {
+    // The actual gateway code path: resume is reached ONLY on 'switched'.
+    if (outcome.kind === 'switched') {
+      if (gate.decide(failedTurnStartedAtMs) === 'resume') restart()
+    }
+  }
+
+  it('switched → restart fires exactly once', () => {
+    const clk = fakeClock()
+    const gate = createFleetFallbackResumeGate({ nowFn: clk.now })
+    let restarts = 0
+    simulateDispatch(gate, { kind: 'switched' }, clk.now(), () => restarts++)
+    expect(restarts).toBe(1)
+  })
+
+  it('all-blocked → decide() is never consulted, restart never fires', () => {
+    const clk = fakeClock()
+    const gate = createFleetFallbackResumeGate({ nowFn: clk.now })
+    let restarts = 0
+    simulateDispatch(gate, { kind: 'all-blocked' }, clk.now(), () => restarts++)
+    expect(restarts).toBe(0)
+    // The gate stayed unarmed, so a subsequent real switch still resumes.
+    simulateDispatch(gate, { kind: 'switched' }, clk.now(), () => restarts++)
+    expect(restarts).toBe(1)
+  })
+
+  it('a 429 storm of switched outcomes restarts exactly once', () => {
+    const clk = fakeClock()
+    const gate = createFleetFallbackResumeGate({ nowFn: clk.now, singleFlightMs: 60_000 })
+    let restarts = 0
+    for (let i = 0; i < 5; i++) {
+      simulateDispatch(gate, { kind: 'switched' }, clk.now(), () => restarts++)
+      clk.advance(1_000)
+    }
+    expect(restarts).toBe(1)
+  })
+
+  it('a stale switched outcome does not restart', () => {
+    const clk = fakeClock()
+    const gate = createFleetFallbackResumeGate({ nowFn: clk.now })
+    let restarts = 0
+    const ancient = clk.now() - (DEFAULT_RESUME_MAX_AGE_MS + 1)
+    simulateDispatch(gate, { kind: 'switched' }, ancient, () => restarts++)
+    expect(restarts).toBe(0)
+  })
+})

package/telegram-plugin/tests/gateway-clean-shutdown-marker.test.ts

@@ -35,6 +35,7 @@ import {
   readCleanShutdownMarker,
   clearCleanShutdownMarker,
   shouldSuppressRecoveryBanner,
+  shouldSuppressBootResume,
   resolveShutdownMarker,
   DEFAULT_MAX_AGE_MS,
   EXTERNAL_RESTART_FALLBACK_REASON,
@@ -344,6 +345,122 @@ describe("resolveShutdownMarker (SIGTERM-handler sequencing)", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Boot-resume gate: shouldSuppressBootResume
+// ---------------------------------------------------------------------------
+
+describe("shouldSuppressBootResume", () => {
+  // Core contract: clean shutdown (fresh marker) → suppress; crash (no marker
+  // or stale) → do not suppress; forceAlways override → never suppress.
+
+  it("returns false when no marker is present (crash/OOM — resume as before)", () => {
+    expect(shouldSuppressBootResume(null, Date.now())).toBe(false);
+  });
+
+  it("returns true for a fresh clean-shutdown marker (operator/roll restart — suppress)", () => {
+    const now = 1_700_000_000_000;
+    const marker: CleanShutdownMarker = { ts: now - 5_000, signal: "SIGTERM" };
+    expect(shouldSuppressBootResume(marker, now)).toBe(true);
+  });
+
+  it("returns true at age=0 (marker written right before boot)", () => {
+    const now = 1_700_000_000_000;
+    const marker: CleanShutdownMarker = { ts: now, signal: "SIGTERM" };
+    expect(shouldSuppressBootResume(marker, now)).toBe(true);
+  });
+
+  it("returns false when marker age equals maxAgeMs (boundary is exclusive)", () => {
+    const now = 1_700_000_000_000;
+    const marker: CleanShutdownMarker = { ts: now - DEFAULT_MAX_AGE_MS, signal: "SIGTERM" };
+    expect(shouldSuppressBootResume(marker, now)).toBe(false);
+  });
+
+  it("returns false for a stale marker (drain took >60s — treat as crash)", () => {
+    const now = 1_700_000_000_000;
+    const marker: CleanShutdownMarker = { ts: now - 90_000, signal: "SIGTERM" };
+    expect(shouldSuppressBootResume(marker, now)).toBe(false);
+  });
+
+  it("treats clock skew (future ts) as stale to avoid false suppression", () => {
+    const now = 1_700_000_000_000;
+    const marker: CleanShutdownMarker = { ts: now + 10_000, signal: "SIGTERM" };
+    expect(shouldSuppressBootResume(marker, now)).toBe(false);
+  });
+
+  it("respects a custom maxAgeMs", () => {
+    const now = 1_700_000_000_000;
+    const marker: CleanShutdownMarker = { ts: now - 30_000, signal: "SIGTERM" };
+    expect(shouldSuppressBootResume(marker, now, { maxAgeMs: 60_000 })).toBe(true);
+    expect(shouldSuppressBootResume(marker, now, { maxAgeMs: 10_000 })).toBe(false);
+  });
+
+  it("forceAlways=true disables suppression even for a fresh clean marker (escape hatch)", () => {
+    // SWITCHROOM_BOOT_RESUME_ALWAYS=1 must restore unconditional resume.
+    const now = 1_700_000_000_000;
+    const marker: CleanShutdownMarker = { ts: now - 1_000, signal: "SIGTERM" };
+    expect(shouldSuppressBootResume(marker, now, { forceAlways: true })).toBe(false);
+  });
+
+  it("forceAlways=false has no effect (default behaviour is the gate)", () => {
+    const now = 1_700_000_000_000;
+    const marker: CleanShutdownMarker = { ts: now - 1_000, signal: "SIGTERM" };
+    expect(shouldSuppressBootResume(marker, now, { forceAlways: false })).toBe(true);
+  });
+
+  it("works for SIGTERM and SIGINT (signal value is opaque)", () => {
+    const now = 1_700_000_000_000;
+    expect(shouldSuppressBootResume({ ts: now, signal: "SIGTERM" }, now)).toBe(true);
+    expect(shouldSuppressBootResume({ ts: now, signal: "SIGINT" }, now)).toBe(true);
+  });
+
+  it("works with a marker that carries a reason field (rollout attribution is preserved)", () => {
+    const now = 1_700_000_000_000;
+    const marker: CleanShutdownMarker = {
+      ts: now - 2_000,
+      signal: "SIGTERM",
+      reason: "operator: switchroom update",
+    };
+    expect(shouldSuppressBootResume(marker, now)).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Boot-resume gate: gateway wiring (source-level)
+// ---------------------------------------------------------------------------
+
+describe("gateway.ts boot-resume clean-shutdown gate (source-level)", () => {
+  // Source-grep pins ensure the gate wiring in gateway.ts stays present
+  // after refactors. Pure unit tests on shouldSuppressBootResume cover the
+  // decision logic; these cover the wiring.
+  const gatewaySource = readFileSync(
+    join(import.meta.dir, "..", "gateway", "gateway.ts"),
+    "utf8",
+  );
+
+  it("imports shouldSuppressBootResume from clean-shutdown-marker", () => {
+    expect(gatewaySource).toContain("shouldSuppressBootResume");
+  });
+
+  it("reads the clean-shutdown marker before building the boot-resume inbound", () => {
+    expect(gatewaySource).toContain("bootResumeCleanMarker");
+    expect(gatewaySource).toContain("readCleanShutdownMarker(bootResumeMarkerPath)");
+  });
+
+  it("calls shouldSuppressBootResume with the marker, now, and forceAlways", () => {
+    expect(gatewaySource).toContain("shouldSuppressBootResume(bootResumeCleanMarker, Date.now()");
+    expect(gatewaySource).toContain("forceAlways: bootResumeForceAlways");
+  });
+
+  it("provides the SWITCHROOM_BOOT_RESUME_ALWAYS escape hatch", () => {
+    expect(gatewaySource).toContain("SWITCHROOM_BOOT_RESUME_ALWAYS");
+    expect(gatewaySource).toContain("=== '1'");
+  });
+
+  it("logs a diagnostic when boot-resume is suppressed", () => {
+    expect(gatewaySource).toContain("boot-resume suppressed (clean shutdown");
+  });
+});
+
 describe("gateway.ts shutdown-handler wiring (source-level)", () => {
   // Source-grep pins so a future refactor can't silently drop the
   // reason-preserving + fallback-writing behaviour the 2026-04-24 fix

package/telegram-plugin/tests/gateway-no-reply-single-emit.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
-import { createAnswerStream, __resetDraftIdForTests } from '../answer-stream.js'
+import { createAnswerStream } from '../answer-stream.js'
 
 /**
  * #656 — gateway turn_end no-reply path.
@@ -30,7 +30,6 @@ async function flushMicrotasks(times = 10): Promise<void> {
 let nextMessageId = 5000
 
 beforeEach(() => {
-  __resetDraftIdForTests()
   nextMessageId = 5000
   vi.useFakeTimers()
 })
@@ -46,9 +45,7 @@ describe('#656 — answer-stream retract() at turn_end emits nothing', () => {
     const deleteMessage = vi.fn(async () => {})
 
     const stream = createAnswerStream({
-      chatId: 'chat-no-reply',
-      isPrivateChat: false,
-      minInitialChars: 400,
+      chatId: 'chat-no-reply',      minInitialChars: 400,
       throttleMs: 250,
       sendMessage: sendMessage as never,
       editMessageText: editMessageText as never,
@@ -81,9 +78,7 @@ describe('#656 — answer-stream retract() at turn_end emits nothing', () => {
     const deleteMessage = vi.fn(async () => {})
 
     const stream = createAnswerStream({
-      chatId: 'supergroup-topic',
-      isPrivateChat: false, // supergroup → message transport (no draft)
-      threadId: 4,
+      chatId: 'supergroup-topic',      threadId: 4,
       minInitialChars: Number.MAX_SAFE_INTEGER,
       throttleMs: 250,
       sendMessage: sendMessage as never,
@@ -110,9 +105,7 @@ describe('#656 — answer-stream retract() at turn_end emits nothing', () => {
     const deleteMessage = vi.fn(async () => {})
 
     const stream = createAnswerStream({
-      chatId: 'chat-no-reply',
-      isPrivateChat: false,
-      minInitialChars: 10,
+      chatId: 'chat-no-reply',      minInitialChars: 10,
       throttleMs: THROTTLE,
       sendMessage: sendMessage as never,
       editMessageText: editMessageText as never,

package/telegram-plugin/tests/history.test.ts

@@ -444,6 +444,66 @@ describe('hasOutboundDeliveredSince', () => {
   it('returns false when no history is present for the chat', () => {
     expect(hasOutboundDeliveredSince('-999', 0)).toBe(false)
   })
+
+  // #2474 follow-up — the duplicate-represent guard passes a LOW minChars so a
+  // terse-but-genuine reply counts as "the user was answered". The escalate
+  // branch keeps the 200-char default.
+  describe('minChars parameter (decoupled represent-guard threshold)', () => {
+    it('default threshold (200) does NOT count a terse real reply', () => {
+      const openedAt = 1_000_000 * 1000
+      recordOutbound({
+        chat_id: '-100',
+        thread_id: null,
+        message_ids: [10],
+        texts: ['Yes — done.'], // < 200 chars
+        ts: 1_000_001,
+      })
+      // escalate-branch behavior is unchanged: a terse reply is NOT substantive
+      expect(hasOutboundDeliveredSince('-100', openedAt)).toBe(false)
+    })
+
+    it('minChars=1 DOES count a terse real reply (fixes the #2472 terse-reply gap)', () => {
+      const openedAt = 1_000_000 * 1000
+      recordOutbound({
+        chat_id: '-100',
+        thread_id: null,
+        message_ids: [10],
+        texts: ['Merged, all three landed.'], // genuine short reply
+        ts: 1_000_001,
+      })
+      // represent-guard threshold: any real reply suppresses the duplicate
+      expect(hasOutboundDeliveredSince('-100', openedAt, undefined, 1)).toBe(true)
+    })
+
+    it('minChars=1 still does NOT count an empty/whitespace-only row', () => {
+      // A degenerate outbound (no real content) must never read as "answered",
+      // even at the lowest threshold — minChars is clamped to >= 1.
+      const openedAt = 1_000_000 * 1000
+      recordOutbound({
+        chat_id: '-100',
+        thread_id: null,
+        message_ids: [10],
+        texts: [''],
+        ts: 1_000_001,
+      })
+      expect(hasOutboundDeliveredSince('-100', openedAt, undefined, 1)).toBe(false)
+      // minChars=0 is clamped up to 1, so an empty row is still excluded
+      expect(hasOutboundDeliveredSince('-100', openedAt, undefined, 0)).toBe(false)
+    })
+
+    it('minChars=1 respects the thread filter (terse reply scoped to its thread)', () => {
+      const openedAt = 1_000_000 * 1000
+      recordOutbound({
+        chat_id: '-100',
+        thread_id: 5,
+        message_ids: [10],
+        texts: ['ok'],
+        ts: 1_000_001,
+      })
+      expect(hasOutboundDeliveredSince('-100', openedAt, 5, 1)).toBe(true)
+      expect(hasOutboundDeliveredSince('-100', openedAt, 6, 1)).toBe(false)
+    })
+  })
 })
 
 describe('secret redaction at persistence (both directions)', () => {

package/telegram-plugin/tests/model-unavailable.test.ts

@@ -151,6 +151,124 @@ describe('detectModelUnavailable — reset-time extraction', () => {
   })
 })
 
+// ─── SESSION-cap (time-only) reset parsing — auth-failover-stall Fix 2 ─────────
+//
+// A session cap surfaces as "resets <time>" with NO month/day. Pre-fix this
+// was unparseable → resetAt undefined → the 429 inference path applied the +7d
+// weekly floor, benching the account for a WEEK. The new branch resolves it to
+// the NEXT occurrence of that wall-clock time (hours away), tz-aware.
+describe('detectModelUnavailable — time-only session-cap reset (Fix 2)', () => {
+  const HOUR = 3600_000
+  const WEEK = 7 * 24 * HOUR
+
+  // Next occurrence of a wall-clock time in a tz must be ≤24h away — and
+  // crucially NOT the +7d weekly floor.
+  function expectHoursAway(d: Date | undefined): void {
+    expect(d).toBeInstanceOf(Date)
+    const deltaMs = (d as Date).getTime() - Date.now()
+    expect(deltaMs).toBeGreaterThan(0)
+    expect(deltaMs).toBeLessThanOrEqual(24 * HOUR + 60_000)
+    // The whole point: never the weekly floor.
+    expect(deltaMs).toBeLessThan(WEEK - HOUR)
+  }
+
+  // The next wall-clock occurrence of `hour:minute` in `tz` should land on
+  // that exact minute (sanity that we resolved the time, not a fudge).
+  function expectWallClock(d: Date | undefined, tz: string, hour: number, minute = 0): void {
+    expect(d).toBeInstanceOf(Date)
+    const parts = Object.fromEntries(
+      new Intl.DateTimeFormat('en-US', {
+        timeZone: tz, hour: '2-digit', minute: '2-digit', hour12: false,
+      })
+        .formatToParts(d as Date)
+        .filter((p) => p.type !== 'literal')
+        .map((p) => [p.type, p.value]),
+    )
+    expect(Number(parts.hour) % 24).toBe(hour)
+    expect(Number(parts.minute)).toBe(minute)
+  }
+
+  it('parses "resets 5pm (Australia/Melbourne)" to the next 17:00 there, hours away (NOT +7d)', () => {
+    const d = detectModelUnavailable(
+      "You've hit your session limit · resets 5pm (Australia/Melbourne)",
+    )
+    expect(d?.kind).toBe('quota_exhausted')
+    expectHoursAway(d?.resetAt)
+    expectWallClock(d?.resetAt, 'Australia/Melbourne', 17, 0)
+  })
+
+  it('parses the "at"-prefixed form — "resets at 5pm (Australia/Melbourne)" (parity with wedge-watchdog parseWeeklyReset)', () => {
+    // wedge-watchdog's parseWeeklyReset time-only regex accepts an optional
+    // "(?:at\s+)?" token; this parser must accept the IDENTICAL grammar or the
+    // "at"-prefixed string falls through to the +7d weekly floor — the
+    // week-long-bench bug this PR exists to kill.
+    const d = detectModelUnavailable(
+      "You've hit your session limit · resets at 5pm (Australia/Melbourne)",
+    )
+    expect(d?.kind).toBe('quota_exhausted')
+    expectHoursAway(d?.resetAt)
+    expectWallClock(d?.resetAt, 'Australia/Melbourne', 17, 0)
+  })
+
+  it('parses am times — "resets 8:50am (Australia/Melbourne)"', () => {
+    const d = detectModelUnavailable("You've hit your limit · resets 8:50am (Australia/Melbourne)")
+    expect(d?.kind).toBe('quota_exhausted')
+    expectHoursAway(d?.resetAt)
+    expectWallClock(d?.resetAt, 'Australia/Melbourne', 8, 50)
+  })
+
+  it('parses a time WITHOUT minutes — "resets 9am (UTC)"', () => {
+    const d = detectModelUnavailable('hit your limit · resets 9am (UTC)')
+    expect(d?.kind).toBe('quota_exhausted')
+    expectHoursAway(d?.resetAt)
+    expectWallClock(d?.resetAt, 'UTC', 9, 0)
+  })
+
+  it('parses a time WITHOUT a tz label (best-effort UTC) — "resets 11pm"', () => {
+    const d = detectModelUnavailable('usage limit hit · resets 11pm')
+    expect(d?.kind).toBe('quota_exhausted')
+    expectHoursAway(d?.resetAt)
+    expectWallClock(d?.resetAt, 'UTC', 23, 0)
+  })
+
+  it('parses 24-hour clock times — "resets 17:00 (UTC)"', () => {
+    const d = detectModelUnavailable('hit your limit · resets 17:00 (UTC)')
+    expect(d?.kind).toBe('quota_exhausted')
+    expectHoursAway(d?.resetAt)
+    expectWallClock(d?.resetAt, 'UTC', 17, 0)
+  })
+
+  it('STILL parses a bare ISO-8601 reset (calendar-path regression guard)', () => {
+    const d = detectModelUnavailable('quota exhausted, retry at 2026-05-03T11:00:00Z')
+    expect(d?.resetAt?.toISOString()).toBe('2026-05-03T11:00:00.000Z')
+  })
+
+  it('a month/day "resets" string is NOT hijacked into the time-only branch', () => {
+    // The negative lookahead must reject "May"/"Jun" so a date-bearing string
+    // never resolves to "tomorrow at HH:MM". (The month/day+time calendar form
+    // itself does not currently resolve to a Date — that is pre-existing
+    // behaviour; the load-bearing guard is that the time-only branch leaves it
+    // alone rather than producing a WRONG hours-away time.)
+    const may = detectModelUnavailable("You're out of extra usage · resets May 3, 11am")
+    expect(may?.kind).toBe('quota_exhausted')
+    // If the time-only branch had wrongly fired, resetAt would be ≤24h away.
+    if (may?.resetAt) {
+      const deltaMs = may.resetAt.getTime() - Date.now()
+      // A genuine May-3 resolution is many days away (or in the past); never the
+      // bare next-11am-tomorrow the time-only branch would have produced.
+      expect(Math.abs(deltaMs)).toBeGreaterThan(2 * 24 * HOUR)
+    }
+    const jun = detectModelUnavailable(
+      "hit your limit · resets Jun 9, 5am (Australia/Melbourne)",
+    )
+    expect(jun?.kind).toBe('quota_exhausted')
+    if (jun?.resetAt) {
+      const deltaMs = jun.resetAt.getTime() - Date.now()
+      expect(Math.abs(deltaMs)).toBeGreaterThan(2 * 24 * HOUR)
+    }
+  })
+})
+
 // ─── formatModelUnavailableCard ──────────────────────────────────────────────
 
 describe('formatModelUnavailableCard — actionable card', () => {