@zooid/transport-matrix 0.8.0 → 0.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zooid/transport-matrix",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "Matrix Application Service transport for zooid. Routes inbound Matrix messages to ACP agents and posts replies plus approval custom events back to threads.",
   "type": "module",
   "license": "MIT",
@@ -28,8 +28,8 @@
     "marked": "^18.0.4",
     "sanitize-html": "^2.17.4",
     "yaml": "^2.5.0",
-    "@zooid/acp-client": "^0.8.0",
-    "@zooid/core": "^0.8.0"
+    "@zooid/acp-client": "^0.9.1",
+    "@zooid/core": "^0.9.1"
   },
   "devDependencies": {
     "@hono/node-server": "^1.13.0",

package/src/bot-pool.test.ts

@@ -248,8 +248,14 @@ describe('BotPool.bootstrap workforce-space attachment', () => {
       ],
     )
     await pool.bootstrap({ spaceRoomId: '!space:zoon.local', asUserId: '@zooid:zoon.local' })
+    // Created BY the AS sender bot (room owner/admin), never by the agent —
+    // agents join as plain members, never room admins.
     expect(createRoom).toHaveBeenCalledWith(
-      expect.objectContaining({ roomAliasName: 'design', restrictedToSpaceId: '!space:zoon.local' }),
+      expect.objectContaining({
+        roomAliasName: 'design',
+        restrictedToSpaceId: '!space:zoon.local',
+        senderUserId: '@zooid:zoon.local',
+      }),
     )
   })
 

package/src/bot-pool.ts

@@ -48,7 +48,7 @@ export class BotPool {
         console.warn(`[matrix] setDisplayName(${a.userId}) failed: ${(err as Error).message}`)
       }
       // Make each agent a member of the workforce space. That covers two
-      // things at once: the eco.zoon.workforce roster is now backed by
+      // things at once: the dev.zooid.workforce roster is now backed by
       // actual space membership (so the Zoon client's member autocomplete
       // works across rooms), and every restricted child room's allow rule
       // is satisfied without per-room invites.
@@ -82,7 +82,13 @@ export class BotPool {
               } else {
                 const colon = room.indexOf(':')
                 const aliasLocalpart = colon > 1 ? room.slice(1, colon) : room.slice(1)
-                const sender = opts.adminUserId ?? a.userId
+                // Workstation-created rooms are owned by the AS sender bot (PL
+                // 100, already seeded in the power override below). Agents join
+                // as plain members and must never be room admins. The human
+                // operator is invited + seeded at PL 100, but can't be the
+                // creator under a workstation-scoped namespace — the AS token
+                // can't impersonate a non-namespaced human.
+                const sender = opts.asUserId ?? opts.adminUserId ?? a.userId
                 const userPowerLevels = buildUserPowerLevels(
                   opts.asUserId,
                   opts.adminUserIds,

package/src/context-provider.ts

@@ -43,7 +43,7 @@ export class MatrixContextProvider implements TransportContextProvider {
 
   async getRoomHistory(channelId: string, hopts: HistoryOptions): Promise<HistoryPage> {
     // Server-side filter: only `m.room.message` events. Without this we'd
-    // burn the page budget on reactions, `eco.zoon.*` custom events, typing
+    // burn the page budget on reactions, `dev.zooid.*` custom events, typing
     // notifications, etc., and routinely return empty pages with a stale
     // `has_more` cursor.
     const { chunk, end } = await this.opts.client.fetchRoomMessages({

package/src/event-encoders.test.ts

@@ -9,6 +9,7 @@ import {
   toUpdateBody,
   toPlanBody,
   toErrorBody,
+  toAvailableCommandsBody,
 } from './event-encoders.js'
 
 describe('toToolCallBody', () => {
@@ -124,6 +125,27 @@ describe('toPlanBody', () => {
   })
 })
 
+describe('toAvailableCommandsBody', () => {
+  it('encodes available_commands into the body ZNC021 decodes', () => {
+    expect(
+      toAvailableCommandsBody({
+        type: 'available_commands',
+        sessionId: 's-1',
+        commands: [
+          { name: 'plan', description: 'Switch to plan mode' },
+          { name: 'compact', description: 'Compact the context' },
+        ],
+      }),
+    ).toEqual({
+      session_id: 's-1',
+      available_commands: [
+        { name: 'plan', description: 'Switch to plan mode' },
+        { name: 'compact', description: 'Compact the context' },
+      ],
+    })
+  })
+})
+
 describe('toErrorBody', () => {
   const threadRoot = '$root-event-id'
 

package/src/event-encoders.ts

@@ -1,4 +1,5 @@
 import type {
+  AvailableCommandsEvent,
   PlanEvent,
   TapEvent,
   ToolCallEvent,
@@ -66,6 +67,18 @@ export function toPlanBody(evt: PlanEvent): Record<string, unknown> {
   }
 }
 
+export function toAvailableCommandsBody(
+  evt: AvailableCommandsEvent,
+): Record<string, unknown> {
+  return {
+    session_id: evt.sessionId,
+    available_commands: evt.commands.map((c) => ({
+      name: c.name,
+      description: c.description,
+    })),
+  }
+}
+
 const RECOVERY_URLS: Partial<Record<string, string>> = {
   auth_missing: 'https://zooid.dev/docs/guides/run-in-container#authentication-that-carries-over',
   auth_invalid: 'https://zooid.dev/docs/guides/run-in-container#authentication-that-carries-over',

package/src/identity.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect } from 'vitest'
+import {
+  isValidWorkstation,
+  isValidAgentKey,
+  agentMxid,
+  splitAgentLocalpart,
+  workstationUserNamespace,
+} from './identity.js'
+
+describe('workstation / agent grammar', () => {
+  it('accepts dot-free lowercase-alnum-hyphen', () => {
+    expect(isValidWorkstation('laptop')).toBe(true)
+    expect(isValidWorkstation('ec2-prod')).toBe(true)
+    expect(isValidAgentKey('docs')).toBe(true)
+  })
+  it('rejects dots (the workstation/agent separator) and bad chars', () => {
+    expect(isValidWorkstation('lap.top')).toBe(false) // dot is the boundary, never inside
+    expect(isValidWorkstation('Laptop')).toBe(false) // strict ASCII lowercase
+    expect(isValidWorkstation('lap_top')).toBe(false)
+    expect(isValidWorkstation('')).toBe(false)
+    expect(isValidAgentKey('a.b')).toBe(false)
+  })
+})
+
+describe('agentMxid', () => {
+  it('builds @{workstation}.{agent}:server', () => {
+    expect(agentMxid('laptop', 'assistant', 'zoon.eco')).toBe('@laptop.assistant:zoon.eco')
+  })
+  it('throws on invalid parts', () => {
+    expect(() => agentMxid('lap.top', 'assistant', 'zoon.eco')).toThrow()
+    expect(() => agentMxid('laptop', 'a.b', 'zoon.eco')).toThrow()
+  })
+})
+
+describe('splitAgentLocalpart — split on FIRST dot', () => {
+  it('recovers (workstation, agent)', () => {
+    expect(splitAgentLocalpart('laptop.assistant')).toEqual({
+      workstation: 'laptop',
+      agent: 'assistant',
+    })
+  })
+  it('throws when there is no separator', () => {
+    expect(() => splitAgentLocalpart('zooid')).toThrow()
+  })
+})
+
+describe('workstationUserNamespace', () => {
+  it('emits an escaped-dot exclusive regex for the workstation', () => {
+    // The literal dot must be escaped so @{workstation}.* does not also match @{workstation}X*
+    expect(workstationUserNamespace('laptop', 'zoon.eco')).toBe('@laptop\\..*:zoon.eco')
+  })
+})

package/src/identity.ts

@@ -0,0 +1,27 @@
+// A workstation id (and an agent key) must be "slug-shaped": kebab-case,
+// MXID/alias-safe. SLUG_RE names the *format*; the domain noun is workstation.
+export const SLUG_RE = /^[a-z0-9-]+$/
+export const AGENT_KEY_RE = /^[a-z0-9-]+$/
+
+export const isValidWorkstation = (s: string): boolean => SLUG_RE.test(s)
+export const isValidAgentKey = (s: string): boolean => AGENT_KEY_RE.test(s)
+
+export function agentMxid(workstation: string, agent: string, serverName: string): string {
+  if (!isValidWorkstation(workstation))
+    throw new Error(`invalid workstation: ${JSON.stringify(workstation)}`)
+  if (!isValidAgentKey(agent)) throw new Error(`invalid agent key: ${JSON.stringify(agent)}`)
+  return `@${workstation}.${agent}:${serverName}`
+}
+
+export function splitAgentLocalpart(localpart: string): { workstation: string; agent: string } {
+  const i = localpart.indexOf('.') // first dot is the boundary; workstation/agent are dot-free
+  if (i <= 0 || i === localpart.length - 1)
+    throw new Error(`not a workstation.agent localpart: ${localpart}`)
+  return { workstation: localpart.slice(0, i), agent: localpart.slice(i + 1) }
+}
+
+export function workstationUserNamespace(workstation: string, serverName: string): string {
+  if (!isValidWorkstation(workstation))
+    throw new Error(`invalid workstation: ${JSON.stringify(workstation)}`)
+  return `@${workstation}\\..*:${serverName}` // escaped dot — exclusive to this workstation's agents
+}

package/src/index.ts

@@ -4,6 +4,15 @@ export { MatrixContextProvider } from './context-provider.js'
 export type { MatrixContextProviderOpts } from './context-provider.js'
 export { renderRegistration } from './registration.js'
 export type { MatrixTransportConfig } from './registration.js'
+export {
+  isValidWorkstation,
+  isValidAgentKey,
+  agentMxid,
+  splitAgentLocalpart,
+  workstationUserNamespace,
+  SLUG_RE,
+  AGENT_KEY_RE,
+} from './identity.js'
 export { extractMentions } from './mentions.js'
 export type { MaybeMessage } from './mentions.js'
 export { route, isMediaMsgtype, MEDIA_MSGTYPES } from './router.js'
@@ -11,6 +20,8 @@ export type { AgentBinding, RouteMatch } from './router.js'
 export { BotPool } from './bot-pool.js'
 export { createMatrixTransport } from './transport.js'
 export type { CreateMatrixTransportOptions, MediaClientLike } from './transport.js'
+export { SyncLoop } from './sync-loop.js'
+export type { SyncLoopOptions, SyncResponse, SyncClient } from './sync-loop.js'
 export { ensureDefaultChannel, ensureWorkforceSpace, serverNameFromMxid } from './space-provisioner.js'
 export type { EnsureDefaultChannelOpts, EnsureSpaceOpts } from './space-provisioner.js'
 export {

package/src/matrix-client.test.ts

@@ -287,7 +287,7 @@ describe('MatrixClient', () => {
 
   it('sends a custom event type when content type is set', async () => {
     const fetch = fakeFetch(async ({ url, init }) => {
-      expect(url).toMatch(/\/send\/eco\.zoon\.approval_request\//)
+      expect(url).toMatch(/\/send\/dev\.zooid\.approval_request\//)
       const body = JSON.parse(init.body as string)
       expect(body.approval_id).toBe('a1')
       return new Response(JSON.stringify({ event_id: '$x' }), { status: 200 })
@@ -300,7 +300,7 @@ describe('MatrixClient', () => {
     await client.sendCustomEvent({
       roomId: '!r:example.com',
       asUserId: '@architect:example.com',
-      eventType: 'eco.zoon.approval_request',
+      eventType: 'dev.zooid.approval_request',
       content: { approval_id: 'a1', description: 'Run: git push' },
     })
   })
@@ -445,6 +445,62 @@ describe('MatrixClient.createRoom userPowerLevels', () => {
   })
 })
 
+describe('MatrixClient.leaveRoom', () => {
+  it('leaves (rejects) a room as the impersonated user, with a reason', async () => {
+    const fetch = fakeFetch(async ({ url, init }) => {
+      expect(url).toBe(
+        'https://hs.example.com/_matrix/client/v3/rooms/!r%3Aexample.com/leave' +
+          '?user_id=%40zooid%3Aexample.com',
+      )
+      expect(init.method).toBe('POST')
+      expect(JSON.parse(init.body as string)).toEqual({ reason: 'no thanks' })
+      return new Response('{}', { status: 200 })
+    })
+    const client = new MatrixClient({
+      homeserver: 'https://hs.example.com',
+      asToken: 'as-secret',
+      fetch: fetch as unknown as typeof globalThis.fetch,
+    })
+    await client.leaveRoom('!r:example.com', '@zooid:example.com', { reason: 'no thanks' })
+  })
+
+  it('sends an empty body when no reason is given', async () => {
+    const fetch = fakeFetch(async ({ init }) => {
+      expect(JSON.parse(init.body as string)).toEqual({})
+      return new Response('{}', { status: 200 })
+    })
+    const client = new MatrixClient({
+      homeserver: 'https://hs.example.com',
+      asToken: 'as-secret',
+      fetch: fetch as unknown as typeof globalThis.fetch,
+    })
+    await client.leaveRoom('!r:example.com', '@zooid:example.com')
+  })
+})
+
+describe('MatrixClient.sync (impersonated)', () => {
+  it('GETs /sync with ?user_id=, as_token bearer, since + timeout', async () => {
+    const fetch = vi.fn(async () =>
+      new Response(JSON.stringify({ next_batch: 's2', rooms: { join: {} } }), { status: 200 }),
+    )
+    const c = new MatrixClient({
+      homeserver: 'https://zoon.eco',
+      asToken: 'as-tok',
+      fetch: fetch as unknown as typeof globalThis.fetch,
+    })
+    const out = await c.sync({ asUserId: '@laptop.docs:zoon.eco', since: 's1', timeoutMs: 30000 })
+
+    expect(out.next_batch).toBe('s2')
+    const url = new URL(fetch.mock.calls[0]![0] as string)
+    expect(url.pathname).toBe('/_matrix/client/v3/sync')
+    expect(url.searchParams.get('user_id')).toBe('@laptop.docs:zoon.eco')
+    expect(url.searchParams.get('since')).toBe('s1')
+    expect(url.searchParams.get('timeout')).toBe('30000')
+    const headers = (fetch.mock.calls[0]![1] as RequestInit).headers as Record<string, string>
+    expect(headers.Authorization).toBe('Bearer as-tok')
+  })
+})
+
 describe('MatrixClient.createRoom restricted', () => {
   it('injects a restricted join rule referencing the space when restrictedToSpaceId is set', async () => {
     const fetch = fakeFetch(async ({ url, init }) => {

package/src/matrix-client.ts

@@ -222,6 +222,25 @@ export class MatrixClient {
     throw new Error(`invite(${opts.targetUserId}) failed: ${r.status}`)
   }
 
+  async leaveRoom(
+    roomId: string,
+    asUserId: string,
+    opts?: { reason?: string },
+  ): Promise<void> {
+    const url =
+      `${this.homeserver}/_matrix/client/v3/rooms/${encodeURIComponent(roomId)}/leave` +
+      `?user_id=${encodeURIComponent(asUserId)}`
+    const r = await this.fetch(url, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${this.asToken}`,
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify(opts?.reason ? { reason: opts.reason } : {}),
+    })
+    if (!r.ok) throw new Error(`leaveRoom(${roomId}, ${asUserId}) failed: ${r.status}`)
+  }
+
   async joinRoom(roomIdOrAlias: string, asUserId: string): Promise<void> {
     const url =
       `${this.homeserver}/_matrix/client/v3/join/${encodeURIComponent(roomIdOrAlias)}` +
@@ -401,6 +420,38 @@ export class MatrixClient {
     return (await r.json()) as { joined: Record<string, { display_name?: string }> }
   }
 
+  async sync(opts: {
+    asUserId: string
+    since?: string | null
+    timeoutMs?: number
+  }): Promise<{
+    next_batch: string
+    rooms: {
+      join: Record<string, {
+        timeline: { events: Record<string, unknown>[]; prev_batch?: string; limited?: boolean }
+      }>
+    }
+  }> {
+    const params = new URLSearchParams({
+      user_id: opts.asUserId,
+      timeout: String(opts.timeoutMs ?? 30_000),
+    })
+    if (opts.since) params.set('since', opts.since)
+    const url = `${this.homeserver}/_matrix/client/v3/sync?${params.toString()}`
+    const r = await this.fetch(url, {
+      headers: { Authorization: `Bearer ${this.asToken}` },
+    })
+    if (!r.ok) throw new Error(`sync(${opts.asUserId}) failed: ${r.status}`)
+    return r.json() as Promise<{
+      next_batch: string
+      rooms: {
+        join: Record<string, {
+          timeline: { events: Record<string, unknown>[]; prev_batch?: string; limited?: boolean }
+        }>
+      }
+    }>
+  }
+
   async fetchRoomName(roomId: string, asUserId: string): Promise<string | null> {
     const url =
       `${this.homeserver}/_matrix/client/v3/rooms/${encodeURIComponent(roomId)}` +

package/src/registration.test.ts

@@ -1,4 +1,5 @@
 import { describe, it, expect } from 'vitest'
+import { parse } from 'yaml'
 import { renderRegistration, type MatrixTransportConfig } from './registration.js'
 
 const baseConfig: MatrixTransportConfig = {
@@ -39,3 +40,22 @@ describe('renderRegistration', () => {
     expect(yaml).toContain('rate_limited: false')
   })
 })
+
+it('renders a workstation-scoped EXCLUSIVE registration', () => {
+  const y = parse(
+    renderRegistration({
+      id: 'laptop',
+      url: 'http://10.0.1.5:9099',
+      homeserver: 'https://zoon.eco',
+      asToken: 'as-x',
+      hsToken: 'hs-x',
+      senderLocalpart: 'laptop',
+      userNamespace: '@laptop\\..*:zoon.eco',
+      exclusive: true,
+    }),
+  )
+  expect(y.sender_localpart).toBe('laptop')
+  expect(y.url).toBe('http://10.0.1.5:9099')
+  expect(y.namespaces.users[0]).toEqual({ exclusive: true, regex: '@laptop\\..*:zoon.eco' })
+  expect(y.namespaces.rooms).toEqual([]) // never fence by room id
+})

package/src/sync-loop.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect, vi } from 'vitest'
+import { SyncLoop } from './sync-loop.js'
+
+const evt = (id: string, roomId: string) => ({
+  type: 'm.room.message',
+  event_id: id,
+  sender: '@me:zoon.eco',
+  room_id: roomId,
+  content: { msgtype: 'm.text', body: 'hi' },
+})
+
+function fakeClient(pages: unknown[]) {
+  let i = 0
+  return {
+    sync: vi.fn(async () => pages[Math.min(i++, pages.length - 1)]),
+  }
+}
+
+describe('SyncLoop', () => {
+  it('dispatches each timeline event once and persists next_batch', async () => {
+    const store = new Map<string, string>()
+    const dispatched: string[] = []
+    const client = fakeClient([
+      { next_batch: 's1', rooms: { join: { '!r': { timeline: { events: [evt('a', '!r')] } } } } },
+      { next_batch: 's2', rooms: { join: { '!r': { timeline: { events: [evt('b', '!r')] } } } } },
+      { next_batch: 's2', rooms: { join: {} } },
+    ])
+    const loop = new SyncLoop({
+      client: client as never,
+      asUserId: '@laptop.docs:zoon.eco',
+      loadSince: () => store.get('docs') ?? null,
+      saveSince: (s) => store.set('docs', s),
+      onEvent: (e) => dispatched.push(e.event_id as string),
+    })
+    await loop.tick()
+    await loop.tick()
+    expect(dispatched).toEqual(['a', 'b'])
+    expect(store.get('docs')).toBe('s2')
+  })
+
+  it('resumes from the persisted since (no reprocessing across restart)', async () => {
+    const store = new Map<string, string>([['docs', 's-persisted']])
+    const client = fakeClient([{ next_batch: 's3', rooms: { join: {} } }])
+    const loop = new SyncLoop({
+      client: client as never,
+      asUserId: '@laptop.docs:zoon.eco',
+      loadSince: () => store.get('docs') ?? null,
+      saveSince: (s) => store.set('docs', s),
+      onEvent: () => {},
+    })
+    await loop.tick()
+    expect((client.sync as ReturnType<typeof vi.fn>).mock.calls[0][0].since).toBe('s-persisted')
+  })
+
+  it('tolerates an idle sync with no `rooms` key (real homeservers omit it)', async () => {
+    const store = new Map<string, string>()
+    const dispatched: string[] = []
+    // Real Tuwunel returns just { next_batch } on an idle incremental sync.
+    const client = fakeClient([{ next_batch: 's-idle' }])
+    const loop = new SyncLoop({
+      client: client as never,
+      asUserId: '@laptop.docs:zoon.eco',
+      loadSince: () => store.get('docs') ?? null,
+      saveSince: (s) => store.set('docs', s),
+      onEvent: (e) => dispatched.push(e.event_id as string),
+    })
+    await expect(loop.tick()).resolves.toBeUndefined()
+    expect(dispatched).toEqual([])
+    expect(store.get('docs')).toBe('s-idle') // cursor still advances
+  })
+
+  it('tolerates a joined room with no `timeline` (state/ephemeral-only update)', async () => {
+    const store = new Map<string, string>()
+    const dispatched: string[] = []
+    // A room can appear in rooms.join carrying only state — no timeline key.
+    const client = fakeClient([
+      { next_batch: 's-state', rooms: { join: { '!r': { state: { events: [] } } } } },
+    ])
+    const loop = new SyncLoop({
+      client: client as never,
+      asUserId: '@laptop.docs:zoon.eco',
+      loadSince: () => store.get('docs') ?? null,
+      saveSince: (s) => store.set('docs', s),
+      onEvent: (e) => dispatched.push(e.event_id as string),
+    })
+    await expect(loop.tick()).resolves.toBeUndefined()
+    expect(dispatched).toEqual([])
+    expect(store.get('docs')).toBe('s-state')
+  })
+
+  it('run() survives a throwing tick and keeps going (no daemon crash)', async () => {
+    let calls = 0
+    let loop!: SyncLoop
+    const client = {
+      sync: vi.fn(async () => {
+        calls++
+        if (calls === 1) throw new Error('transient /sync 502')
+        loop.stop() // recovered on the 2nd tick — end the loop deterministically
+        return { next_batch: 's-ok' }
+      }),
+    }
+    loop = new SyncLoop({
+      client: client as never,
+      asUserId: '@laptop.docs:zoon.eco',
+      loadSince: () => null,
+      saveSince: () => {},
+      onEvent: () => {},
+      retryDelayMs: 1,
+    })
+    await loop.run() // tick 1 throws → backoff → tick 2 recovers → stop → exits
+    expect(calls).toBe(2)
+  })
+})

package/src/sync-loop.ts

@@ -0,0 +1,74 @@
+export interface SyncResponse {
+  next_batch: string
+  // Real homeservers omit `rooms` (and `rooms.join`) entirely on an idle
+  // incremental sync — both are optional.
+  rooms?: {
+    join?: Record<string, {
+      // A joined room may carry only state/ephemeral/account_data on a given
+      // sync, with no `timeline` (or a timeline with no `events`).
+      timeline?: {
+        events?: Record<string, unknown>[]
+        prev_batch?: string
+        limited?: boolean
+      }
+    }>
+  }
+}
+
+export interface SyncClient {
+  sync(opts: { asUserId: string; since: string | null; timeoutMs: number }): Promise<SyncResponse>
+}
+
+export interface SyncLoopOptions {
+  client: SyncClient
+  asUserId: string
+  loadSince: () => string | null
+  saveSince: (since: string) => void
+  onEvent: (evt: Record<string, unknown>) => void | Promise<void>
+  timeoutMs?: number
+  /** Backoff after a failed tick before retrying. Default 5000ms. */
+  retryDelayMs?: number
+}
+
+export class SyncLoop {
+  private readonly opts: SyncLoopOptions
+  private running = false
+
+  constructor(opts: SyncLoopOptions) {
+    this.opts = opts
+  }
+
+  async tick(): Promise<void> {
+    const since = this.opts.loadSince()
+    const res = await this.opts.client.sync({
+      asUserId: this.opts.asUserId,
+      since,
+      timeoutMs: this.opts.timeoutMs ?? 30_000,
+    })
+    for (const [roomId, roomState] of Object.entries(res.rooms?.join ?? {})) {
+      for (const baseEvt of roomState.timeline?.events ?? []) {
+        await this.opts.onEvent({ ...(baseEvt as Record<string, unknown>), room_id: roomId })
+      }
+    }
+    this.opts.saveSince(res.next_batch)
+  }
+
+  async run(): Promise<void> {
+    this.running = true
+    while (this.running) {
+      try {
+        await this.tick()
+      } catch (err) {
+        // A transient /sync failure (network blip, sleep/wake, 5xx) must not
+        // kill the loop — log and back off, then resume from the same `since`.
+        if (!this.running) break
+        console.warn(`[sync-loop] ${this.opts.asUserId} tick failed, retrying:`, err)
+        await new Promise((r) => setTimeout(r, this.opts.retryDelayMs ?? 5_000))
+      }
+    }
+  }
+
+  stop(): void {
+    this.running = false
+  }
+}