agent-messenger 2.31.0 → 2.32.1

package/src/platforms/channeltalk/token-extractor.test.ts

@@ -18,10 +18,60 @@ describe('ChannelTokenExtractor', () => {
   })
 
   describe('getAppDataDir', () => {
+    const originalAppData = process.env.APPDATA
+
+    afterEach(() => {
+      if (originalAppData === undefined) delete process.env.APPDATA
+      else process.env.APPDATA = originalAppData
+    })
+
     it('returns null for unsupported platform', () => {
       const extractor = new ChannelTokenExtractor('freebsd' as NodeJS.Platform)
       expect(extractor.getAppDataDir()).toBeNull()
     })
+
+    it('resolves the rebranded Channel Works directory', () => {
+      // given
+      const tempDir = mkdtempSync(join(tmpdir(), 'channel-appdata-'))
+      tempDirs.push(tempDir)
+      mkdirSync(join(tempDir, 'Channel Works'), { recursive: true })
+      process.env.APPDATA = tempDir
+
+      // when
+      const extractor = new ChannelTokenExtractor('win32')
+
+      // then
+      expect(extractor.getAppDataDir()).toBe(join(tempDir, 'Channel Works'))
+    })
+
+    it('falls back to the legacy Channel Talk directory', () => {
+      // given
+      const tempDir = mkdtempSync(join(tmpdir(), 'channel-appdata-'))
+      tempDirs.push(tempDir)
+      mkdirSync(join(tempDir, 'Channel Talk'), { recursive: true })
+      process.env.APPDATA = tempDir
+
+      // when
+      const extractor = new ChannelTokenExtractor('win32')
+
+      // then
+      expect(extractor.getAppDataDir()).toBe(join(tempDir, 'Channel Talk'))
+    })
+
+    it('prefers Channel Works when an upgraded install keeps both directories', () => {
+      // given
+      const tempDir = mkdtempSync(join(tmpdir(), 'channel-appdata-'))
+      tempDirs.push(tempDir)
+      mkdirSync(join(tempDir, 'Channel Talk'), { recursive: true })
+      mkdirSync(join(tempDir, 'Channel Works'), { recursive: true })
+      process.env.APPDATA = tempDir
+
+      // when
+      const extractor = new ChannelTokenExtractor('win32')
+
+      // then
+      expect(extractor.getAppDataDir()).toBe(join(tempDir, 'Channel Works'))
+    })
   })
 
   describe('getCookiesPath', () => {
@@ -173,6 +223,191 @@ describe('ChannelTokenExtractor', () => {
       ])
     })
 
+    it('ignores look-alike hosts that merely contain a channel domain', async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), 'channel-cookie-db-'))
+      tempDirs.push(tempDir)
+      const dbPath = join(tempDir, 'Cookies')
+      // These hosts all contain a channel domain as a substring but are not the domain nor a
+      // subdomain of it, so nobody who controls one may speak for Channel. They are inserted
+      // first so a substring match would let them shadow the real cookies below.
+      await createCookieDatabase(dbPath, [
+        {
+          name: 'x-account',
+          value: 'imposter-account',
+          encrypted_value: Buffer.alloc(0),
+          host_key: '.channel.works.example.com',
+        },
+        {
+          name: 'ch-session-1',
+          value: 'imposter-session',
+          encrypted_value: Buffer.alloc(0),
+          host_key: '.channel.works.example.com',
+        },
+        { name: 'x-account', value: 'imposter-io', encrypted_value: Buffer.alloc(0), host_key: '.channel.io.evil.net' },
+        { name: 'x-account', value: 'real-account', encrypted_value: Buffer.alloc(0), host_key: '.channel.works' },
+        { name: 'ch-session-1', value: 'real-session', encrypted_value: Buffer.alloc(0), host_key: '.channel.works' },
+      ])
+
+      class TestExtractor extends ChannelTokenExtractor {
+        constructor(private dbPath: string) {
+          super('darwin')
+        }
+
+        override getCookiesPath(): string | null {
+          return this.dbPath
+        }
+      }
+
+      const extractor = new TestExtractor(dbPath)
+      const browserSpy = spyOn(extractor as any, 'extractAllFromBrowserPaths').mockResolvedValue([])
+
+      expect(await extractor.extract()).toEqual([
+        {
+          accountCookie: 'real-account',
+          sessionCookie: 'real-session',
+        },
+      ])
+
+      browserSpy.mockRestore()
+    })
+
+    it('extracts cookies from a subdomain of a channel domain', async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), 'channel-cookie-db-'))
+      tempDirs.push(tempDir)
+      const dbPath = join(tempDir, 'Cookies')
+      // The boundary check must not be so strict that it drops legitimate subdomains.
+      await createCookieDatabase(dbPath, [
+        { name: 'x-account', value: 'account-jwt', encrypted_value: Buffer.alloc(0), host_key: '.desk.channel.works' },
+        { name: 'ch-session-1', value: 'session-jwt', encrypted_value: Buffer.alloc(0), host_key: 'channel.works' },
+      ])
+
+      class TestExtractor extends ChannelTokenExtractor {
+        constructor(private dbPath: string) {
+          super('darwin')
+        }
+
+        override getCookiesPath(): string | null {
+          return this.dbPath
+        }
+      }
+
+      const extractor = new TestExtractor(dbPath)
+      const browserSpy = spyOn(extractor as any, 'extractAllFromBrowserPaths').mockResolvedValue([])
+
+      expect(await extractor.extract()).toEqual([
+        {
+          accountCookie: 'account-jwt',
+          sessionCookie: 'session-jwt',
+        },
+      ])
+
+      browserSpy.mockRestore()
+    })
+
+    it('prefers channel.works cookies over stale legacy channel.io cookies', async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), 'channel-cookie-db-'))
+      tempDirs.push(tempDir)
+      const dbPath = join(tempDir, 'Cookies')
+      // Legacy rows are inserted first so they win a naive find() that ignores the domain.
+      await createCookieDatabase(dbPath, [
+        { name: 'x-account', value: 'stale-account', encrypted_value: Buffer.alloc(0), host_key: '.channel.io' },
+        { name: 'ch-session-1', value: 'stale-session', encrypted_value: Buffer.alloc(0), host_key: '.channel.io' },
+        { name: 'x-account', value: 'live-account', encrypted_value: Buffer.alloc(0), host_key: '.channel.works' },
+        { name: 'ch-session-1', value: 'live-session', encrypted_value: Buffer.alloc(0), host_key: '.channel.works' },
+      ])
+
+      class TestExtractor extends ChannelTokenExtractor {
+        constructor(private dbPath: string) {
+          super('darwin')
+        }
+
+        override getCookiesPath(): string | null {
+          return this.dbPath
+        }
+      }
+
+      const extractor = new TestExtractor(dbPath)
+      const browserSpy = spyOn(extractor as any, 'extractAllFromBrowserPaths').mockResolvedValue([])
+
+      expect(await extractor.extract()).toEqual([
+        {
+          accountCookie: 'live-account',
+          sessionCookie: 'live-session',
+        },
+      ])
+
+      browserSpy.mockRestore()
+    })
+
+    it('never pairs an x-account with a session cookie from the other domain', async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), 'channel-cookie-db-'))
+      tempDirs.push(tempDir)
+      const dbPath = join(tempDir, 'Cookies')
+      // channel.works holds an identity but no session; the only session belongs to channel.io.
+      // The live identity must be returned session-less rather than borrowing the legacy session,
+      // which belongs to a different domain and would not authenticate it.
+      await createCookieDatabase(dbPath, [
+        { name: 'x-account', value: 'works-account', encrypted_value: Buffer.alloc(0), host_key: '.channel.works' },
+        { name: 'x-account', value: 'io-account', encrypted_value: Buffer.alloc(0), host_key: '.channel.io' },
+        { name: 'ch-session-1', value: 'io-session', encrypted_value: Buffer.alloc(0), host_key: '.channel.io' },
+      ])
+
+      class TestExtractor extends ChannelTokenExtractor {
+        constructor(private dbPath: string) {
+          super('darwin')
+        }
+
+        override getCookiesPath(): string | null {
+          return this.dbPath
+        }
+      }
+
+      const extractor = new TestExtractor(dbPath)
+      const browserSpy = spyOn(extractor as any, 'extractAllFromBrowserPaths').mockResolvedValue([])
+
+      expect(await extractor.extract()).toEqual([
+        {
+          accountCookie: 'works-account',
+          sessionCookie: undefined,
+        },
+      ])
+
+      browserSpy.mockRestore()
+    })
+
+    it('extracts cookies stored on the rebranded channel.works domain', async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), 'channel-cookie-db-'))
+      tempDirs.push(tempDir)
+      const dbPath = join(tempDir, 'Cookies')
+      await createCookieDatabase(dbPath, [
+        { name: 'x-account', value: 'account-jwt', encrypted_value: Buffer.alloc(0), host_key: '.channel.works' },
+        { name: 'ch-session-1', value: 'session-jwt', encrypted_value: Buffer.alloc(0), host_key: '.channel.works' },
+      ])
+
+      class TestExtractor extends ChannelTokenExtractor {
+        constructor(private dbPath: string) {
+          super('darwin')
+        }
+
+        override getCookiesPath(): string | null {
+          return this.dbPath
+        }
+      }
+
+      const extractor = new TestExtractor(dbPath)
+      // Browser profiles are stubbed out so a real logged-in browser on the host cannot leak in.
+      const browserSpy = spyOn(extractor as any, 'extractAllFromBrowserPaths').mockResolvedValue([])
+
+      expect(await extractor.extract()).toEqual([
+        {
+          accountCookie: 'account-jwt',
+          sessionCookie: 'session-jwt',
+        },
+      ])
+
+      browserSpy.mockRestore()
+    })
+
     it('returns token with undefined sessionCookie when only x-account is present', async () => {
       const tempDir = mkdtempSync(join(tmpdir(), 'channel-cookie-db-'))
       tempDirs.push(tempDir)

package/src/platforms/channeltalk/token-extractor.ts

@@ -18,14 +18,66 @@ import type { KeychainVariant } from '@/shared/chromium'
 
 import type { ExtractedChannelToken } from './types'
 
-type CookieRow = { name: string; value: string; encrypted_value: Uint8Array | Buffer }
+type CookieRow = { name: string; value: string; encrypted_value: Uint8Array | Buffer; host_key: string }
+
+// Channel Talk was rebranded to Channel Works: the desktop app now stores its cookies under a
+// "Channel Works" directory. Both names are probed, newest first, so upgraded and legacy
+// installs (which keep the old directory around) both resolve.
+const APP_DIR_NAMES = ['Channel Works', 'Channel Talk']
+
+// Cookies for the rebranded channel.works domain and the legacy channel.io domain can coexist in
+// one profile, most likely on a browser that was signed in before and after the rebrand.
+const COOKIE_DOMAINS = ['channel.works', 'channel.io']
+
+/**
+ * Match a cookie's host key against a domain on an exact label boundary: the domain itself, or a
+ * subdomain of it.
+ *
+ * Substring matching is not good enough here. `host_key LIKE '%.channel.works%'` also admits an
+ * unrelated host such as `.channel.works.example.com`, so a cookie planted by anyone who controls
+ * a name of that shape could shadow the real one and be sent to the Channel API as our identity.
+ */
+function hostMatchesDomain(hostKey: string, domain: string): boolean {
+  const host = hostKey.startsWith('.') ? hostKey.slice(1) : hostKey
+  return host === domain || host.endsWith(`.${domain}`)
+}
+
+// Mirrors hostMatchesDomain in SQL so the database does the same boundary-aware narrowing. The
+// domains are hardcoded constants, never caller input, so interpolating them is safe.
+const COOKIE_HOST_FILTER = COOKIE_DOMAINS.map((domain) => `host_key = '${domain}' OR host_key LIKE '%.${domain}'`).join(
+  ' OR ',
+)
 
 const COOKIE_QUERY = `
-  SELECT name, value, encrypted_value FROM cookies
+  SELECT name, value, encrypted_value, host_key FROM cookies
   WHERE name IN ('x-account', 'ch-session-1', 'ch-session')
-  AND host_key LIKE '%.channel.io%'
+  AND (${COOKIE_HOST_FILTER})
 `
 
+function findExistingAppDir(bases: string[]): string | null {
+  for (const base of bases) {
+    for (const name of APP_DIR_NAMES) {
+      const appDir = join(base, name)
+      if (existsSync(appDir)) return appDir
+    }
+  }
+  return null
+}
+
+/**
+ * Split cookie rows into one group per domain, newest domain first, dropping domains with no rows.
+ *
+ * Callers resolve a credential pair from a single group rather than from all rows at once. That
+ * keeps `x-account` and its session cookie from being read off different domains, which would pair
+ * an identity with a session that does not belong to it, and it stops a leftover legacy cookie from
+ * shadowing a live channel.works one.
+ */
+function groupRowsByDomain(rows: CookieRow[]): CookieRow[][] {
+  return COOKIE_DOMAINS.map((domain) => rows.filter((row) => hostMatchesDomain(row.host_key, domain))).filter(
+    (group) => group.length > 0,
+  )
+}
+
 export class ChannelTokenExtractor {
   private platform: NodeJS.Platform
   private decryptor: ChromiumCookieDecryptor
@@ -42,7 +94,7 @@ export class ChannelTokenExtractor {
   getAppDataDir(): string | null {
     switch (this.platform) {
       case 'darwin': {
-        const sandboxedPath = join(
+        const sandboxedBase = join(
           homedir(),
           'Library',
           'Containers',
@@ -50,18 +102,13 @@ export class ChannelTokenExtractor {
           'Data',
           'Library',
           'Application Support',
-          'Channel Talk',
         )
-        if (existsSync(sandboxedPath)) {
-          return sandboxedPath
-        }
-        const directPath = join(homedir(), 'Library', 'Application Support', 'Channel Talk')
-        return existsSync(directPath) ? directPath : null
+        const directBase = join(homedir(), 'Library', 'Application Support')
+        return findExistingAppDir([sandboxedBase, directBase])
       }
       case 'win32': {
         const appdata = process.env.APPDATA || join(homedir(), 'AppData', 'Roaming')
-        const appDir = join(appdata, 'Channel Talk')
-        return existsSync(appDir) ? appDir : null
+        return findExistingAppDir([appdata])
       }
       default:
         return null
@@ -221,12 +268,18 @@ export class ChannelTokenExtractor {
     if (rows.length === 0) return null
 
     const localStatePath = this.getLocalStatePath() ?? undefined
-    const accountCookie = this.getDesktopCookieValue(rows, 'x-account', localStatePath)
-    const sessionCookie =
-      this.getDesktopCookieValue(rows, 'ch-session-1', localStatePath) ??
-      this.getDesktopCookieValue(rows, 'ch-session', localStatePath)
+    for (const group of groupRowsByDomain(rows)) {
+      const accountCookie = this.getDesktopCookieValue(group, 'x-account', localStatePath)
+      if (!accountCookie) continue
 
-    return accountCookie ? { accountCookie, sessionCookie } : null
+      const sessionCookie =
+        this.getDesktopCookieValue(group, 'ch-session-1', localStatePath) ??
+        this.getDesktopCookieValue(group, 'ch-session', localStatePath)
+
+      return { accountCookie, sessionCookie }
+    }
+
+    return null
   }
 
   private async extractFromBrowserCookiePath(cookiePath: string): Promise<ExtractedChannelToken | null> {
@@ -234,12 +287,18 @@ export class ChannelTokenExtractor {
     if (rows.length === 0) return null
 
     const localStatePath = findLocalStatePath(cookiePath) ?? undefined
-    const accountCookie = this.getBrowserCookieValue(rows, 'x-account', localStatePath)
-    const sessionCookie =
-      this.getBrowserCookieValue(rows, 'ch-session-1', localStatePath) ??
-      this.getBrowserCookieValue(rows, 'ch-session', localStatePath)
+    for (const group of groupRowsByDomain(rows)) {
+      const accountCookie = this.getBrowserCookieValue(group, 'x-account', localStatePath)
+      if (!accountCookie) continue
 
-    return accountCookie ? { accountCookie, sessionCookie } : null
+      const sessionCookie =
+        this.getBrowserCookieValue(group, 'ch-session-1', localStatePath) ??
+        this.getBrowserCookieValue(group, 'ch-session', localStatePath)
+
+      return { accountCookie, sessionCookie }
+    }
+
+    return null
   }
 
   private getDesktopCookieValue(rows: CookieRow[], name: string, localStatePath?: string): string | undefined {

package/src/platforms/discord/client.test.ts

@@ -1,6 +1,7 @@
-import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
+import { afterEach, beforeEach, describe, expect, it, spyOn } from 'bun:test'
 
 import { DiscordClient, DiscordError } from './client'
+import type { DiscordReadState } from './types'
 
 describe('DiscordClient', () => {
   const originalFetch = globalThis.fetch
@@ -226,23 +227,50 @@ describe('DiscordClient', () => {
 
       expect(fetchCalls[0].url).toBe('https://discord.com/api/v10/channels/ch1/messages?limit=50')
     })
+
+    it('gets messages around a specific message', async () => {
+      mockResponse([])
+
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      await client.getMessages('ch1', 1, { around: 'msg/1' })
+
+      expect(fetchCalls[0].url).toBe('https://discord.com/api/v10/channels/ch1/messages?around=msg%2F1&limit=1')
+    })
   })
 
   describe('getMessage', () => {
     it('returns single message', async () => {
-      mockResponse({
-        id: 'msg1',
-        channel_id: 'ch1',
-        author: { id: '123', username: 'user1' },
-        content: 'Message 1',
-        timestamp: '2024-01-01T00:00:00.000Z',
-      })
+      mockResponse([
+        {
+          id: 'msg1',
+          channel_id: 'ch1',
+          author: { id: '123', username: 'user1' },
+          content: 'Message 1',
+          timestamp: '2024-01-01T00:00:00.000Z',
+        },
+      ])
 
       const client = await new DiscordClient().login({ token: 'test-token' })
       const message = await client.getMessage('ch1', 'msg1')
 
       expect(message.id).toBe('msg1')
-      expect(fetchCalls[0].url).toBe('https://discord.com/api/v10/channels/ch1/messages/msg1')
+      expect(fetchCalls[0].url).toBe('https://discord.com/api/v10/channels/ch1/messages?around=msg1&limit=1')
+    })
+
+    it('throws when the requested message is not returned', async () => {
+      mockResponse([
+        {
+          id: 'neighbor',
+          channel_id: 'ch1',
+          author: { id: '123', username: 'user1' },
+          content: 'Nearby message',
+          timestamp: '2024-01-01T00:00:00.000Z',
+        },
+      ])
+
+      const client = await new DiscordClient().login({ token: 'test-token' })
+
+      await expect(client.getMessage('ch1', 'missing')).rejects.toEqual(new DiscordError('Message not found', '10008'))
     })
   })
 
@@ -674,5 +702,198 @@ describe('DiscordClient', () => {
 
       expect(fetchCalls.length).toBe(2)
     })
+
+    it('normalizes query strings for the same channel route', async () => {
+      mockResponse([], 200, {
+        'X-RateLimit-Remaining': '0',
+        'X-RateLimit-Reset': String(Date.now() / 1000 + 0.1),
+        'X-RateLimit-Bucket': 'messages-bucket',
+      })
+      mockResponse([])
+
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      await client.getMessages('123456789', 1, { around: 'message-1' })
+
+      const startTime = Date.now()
+      await client.getMessages('123456789', 1, { around: 'message-2' })
+      const elapsed = Date.now() - startTime
+
+      expect(elapsed).toBeGreaterThanOrEqual(50)
+      expect(fetchCalls.length).toBe(2)
+    })
+  })
+
+  describe('getUnreadMentions', () => {
+    const mention = (id: string, channelId: string, guildId?: string) => ({
+      id,
+      channel_id: channelId,
+      author: { id: 'a1', username: 'alice' },
+      content: `mention ${id}`,
+      timestamp: '2024-01-29T10:00:00Z',
+      mention_everyone: false,
+      mentions: [{ id: 'me', username: 'me' }],
+      ...(guildId ? { guild_id: guildId } : {}),
+    })
+
+    const stubReadState = (client: DiscordClient, readState: DiscordReadState[]) =>
+      spyOn(client, 'fetchReadState').mockResolvedValue(readState)
+
+    it('keeps mentions newer than the channel read marker', async () => {
+      // given: one channel with an unread mention (200 > marker 100) and one already read (50 < 100)
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      stubReadState(client, [{ channelId: 'c1', lastMessageId: '100', mentionCount: 1 }])
+      mockResponse([mention('200', 'c1'), mention('50', 'c1')])
+
+      const result = await client.getUnreadMentions()
+
+      // then: only the newer message is unread
+      expect(result.count).toBe(1)
+      expect(result.mentions[0].id).toBe('200')
+      expect(result.mentions[0].mention_count).toBe(1)
+    })
+
+    it('treats an equal snowflake as read', async () => {
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      stubReadState(client, [{ channelId: 'c1', lastMessageId: '100', mentionCount: 1 }])
+      mockResponse([mention('100', 'c1')])
+
+      const result = await client.getUnreadMentions()
+
+      expect(result.count).toBe(0)
+    })
+
+    it('omits mentions for channels with no read-state entry', async () => {
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      stubReadState(client, [])
+      mockResponse([mention('200', 'c1')])
+
+      const result = await client.getUnreadMentions()
+
+      expect(result.count).toBe(0)
+    })
+
+    it('omits channels whose mention_count is zero', async () => {
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      stubReadState(client, [{ channelId: 'c1', lastMessageId: '100', mentionCount: 0 }])
+      mockResponse([mention('200', 'c1')])
+
+      const result = await client.getUnreadMentions()
+
+      expect(result.count).toBe(0)
+    })
+
+    it('includes all mentions when the read marker is null', async () => {
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      stubReadState(client, [{ channelId: 'c1', lastMessageId: null, mentionCount: 2 }])
+      mockResponse([mention('200', 'c1'), mention('50', 'c1')])
+
+      const result = await client.getUnreadMentions()
+
+      expect(result.count).toBe(2)
+    })
+
+    it('reports badgeCount from summed read-state mention counts', async () => {
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      stubReadState(client, [
+        { channelId: 'c1', lastMessageId: '100', mentionCount: 2 },
+        { channelId: 'c2', lastMessageId: '100', mentionCount: 3 },
+      ])
+      mockResponse([mention('200', 'c1')])
+
+      const result = await client.getUnreadMentions()
+
+      expect(result.badgeCount).toBe(5)
+      expect(result.count).toBe(1)
+    })
+
+    it('paginates mention history with a before cursor', async () => {
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      stubReadState(client, [{ channelId: 'c1', lastMessageId: '0', mentionCount: 200 }])
+
+      const firstPage = Array.from({ length: 100 }, (_, i) => mention(String(1000 - i), 'c1'))
+      const secondPage = [mention('900', 'c1')]
+      mockResponse(firstPage)
+      mockResponse(secondPage)
+
+      const result = await client.getUnreadMentions()
+
+      expect(fetchCalls.length).toBe(2)
+      expect(fetchCalls[1].url).toContain('before=901')
+      expect(result.count).toBe(101)
+    })
+
+    it('deduplicates mentions repeated across pages', async () => {
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      stubReadState(client, [{ channelId: 'c1', lastMessageId: '0', mentionCount: 100 }])
+
+      const page = Array.from({ length: 100 }, (_, i) => mention(String(1000 - i), 'c1'))
+      const overlap = [mention('901', 'c1'), mention('800', 'c1')]
+      mockResponse(page)
+      mockResponse(overlap)
+
+      const result = await client.getUnreadMentions()
+
+      const ids = result.mentions.map((m) => m.id)
+      expect(new Set(ids).size).toBe(ids.length)
+    })
+
+    it('caps the scan at limit 1 with a single bounded request', async () => {
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      stubReadState(client, [{ channelId: 'c1', lastMessageId: '0', mentionCount: 5 }])
+      mockResponse([mention('1000', 'c1')])
+
+      const result = await client.getUnreadMentions({ limit: 1 })
+
+      // then: exactly one page requested, capped to the limit, incomplete scan
+      expect(fetchCalls.length).toBe(1)
+      expect(fetchCalls[0].url).toContain('limit=1')
+      expect(result.count).toBe(1)
+      expect(result.complete).toBe(false)
+    })
+
+    it('caps the scan at a custom limit that spans multiple pages', async () => {
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      stubReadState(client, [{ channelId: 'c1', lastMessageId: '0', mentionCount: 200 }])
+
+      const firstPage = Array.from({ length: 100 }, (_, i) => mention(String(1000 - i), 'c1'))
+      const secondPage = Array.from({ length: 50 }, (_, i) => mention(String(900 - i), 'c1'))
+      mockResponse(firstPage)
+      mockResponse(secondPage)
+
+      const result = await client.getUnreadMentions({ limit: 150 })
+
+      // then: second page bounded to remaining 50, scan stops at the cap and is incomplete
+      expect(fetchCalls.length).toBe(2)
+      expect(fetchCalls[1].url).toContain('limit=50')
+      expect(result.count).toBe(150)
+      expect(result.complete).toBe(false)
+    })
+
+    it('marks the scan complete when a short page ends history', async () => {
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      stubReadState(client, [{ channelId: 'c1', lastMessageId: '0', mentionCount: 3 }])
+      mockResponse([mention('1000', 'c1'), mention('999', 'c1')])
+
+      const result = await client.getUnreadMentions()
+
+      expect(result.complete).toBe(true)
+      expect(result.count).toBe(2)
+    })
+
+    it('stops and reports incomplete when the cursor fails to advance', async () => {
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      stubReadState(client, [{ channelId: 'c1', lastMessageId: '0', mentionCount: 200 }])
+
+      const fullPage = Array.from({ length: 100 }, (_, i) => mention(String(1000 - i), 'c1'))
+      const repeatedPage = Array.from({ length: 100 }, (_, i) => mention(String(1000 - i), 'c1'))
+      mockResponse(fullPage)
+      mockResponse(repeatedPage)
+
+      const result = await client.getUnreadMentions()
+
+      // then: the repeated page adds nothing new, so the guard stops the scan as incomplete
+      expect(result.complete).toBe(false)
+      expect(result.count).toBe(100)
+    })
   })
 })