@pellux/goodvibes-tui 1.27.0 → 2.0.1

package/src/daemon/handlers/inbox/index.ts

@@ -1,284 +0,0 @@
-// ---------------------------------------------------------------------------
-// Inbox surface: attaches the HOST handler to the SDK-registered
-// `channels.inbox.list` gateway descriptor.
-//
-// The SDK already declares the method id, input schema, output schema, scopes
-// (read:channels) and HTTP binding (GET /api/channels/inbox). This module does
-// NOT re-declare any of that — it looks the descriptor up via the catalog and
-// attaches an implementation with `registerCatalogHandler` ({ replace: true }).
-//
-// register(ctx, routing) =>
-//   1. registers built-in provider adapter factories (slack/discord/email)
-//   2. constructs adapters with the daemon credential store + a route resolver
-//      bridged from the routing surface (best-effort, never throws)
-//   3. opens the inbox cursor store and seeds an initial poll
-//   4. starts the per-provider polling loops
-//   5. attaches the read-only `channels.inbox.list` handler (no confirm)
-//   6. returns an Unregister that detaches the handler, stops the poller, and
-//      closes the store.
-//
-// The handler reads the persisted feed (filtered by provider/limit/since) and
-// maps the daemon-internal item shape onto the SDK CHANNEL_INBOX_ITEM_SCHEMA
-// wire shape. The redacted `fromDigest` is the only sender value emitted (as
-// `from`); raw sender ids and unredacted bodies never leave the daemon. The
-// monotonic cursor advances to max(receivedAt) in the returned window.
-// ---------------------------------------------------------------------------
-
-import type { HandlerContext } from '../context.ts';
-import type { Unregister } from '../register.ts';
-import { registerCatalogHandler } from '../register.ts';
-import type { RoutingRegistration } from '../index.ts';
-import {
-  buildAdapters,
-  registerAdapterFactory,
-  type AdapterContext,
-  type InboundChannelItem,
-  type RouteResolver,
-} from './provider-adapter.ts';
-import { InboxCursorStore } from './cursor-store.ts';
-import { InboundPoller } from './poller.ts';
-import { createSlackAdapter, SLACK_PROVIDER_ID } from './providers/slack.ts';
-import { createDiscordAdapter, DISCORD_PROVIDER_ID } from './providers/discord.ts';
-import { createEmailAdapter, EMAIL_PROVIDER_ID } from './providers/email.ts';
-import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
-
-export const INBOX_LIST_METHOD_ID = 'channels.inbox.list';
-const DEFAULT_LIMIT = 50;
-const MAX_LIMIT = 500;
-
-/** SDK `channels.inbox.list` input (single optional provider per the schema). */
-export interface InboxListInput {
-  provider?: string;
-  limit?: number;
-  since?: number;
-}
-
-/** One item in the SDK CHANNEL_INBOX_ITEM_SCHEMA wire shape. */
-export interface ChannelInboxItem {
-  id: string;
-  provider: string;
-  kind: string;
-  /** Redacted sender token (sha256First, 16 hex). Never the raw id. */
-  from: string;
-  subject?: string;
-  bodyPreview: string;
-  receivedAt: number;
-  unread: boolean;
-  routeId?: string;
-}
-
-/** SDK `channels.inbox.list` output (objectSchema: items/total/truncated/cursor?). */
-export interface InboxListOutput {
-  items: ChannelInboxItem[];
-  total: number;
-  truncated: boolean;
-  cursor?: string;
-}
-
-/** Start/stop control over the poll loops, handed to a leadership gate. */
-export interface InboxPollingControl {
-  /** Seed one poll and arm the loops. Resolves once polling has begun. */
-  start(): Promise<void>;
-  /** Disarm the loops. Resolves once no further poll can run. */
-  stop(): Promise<void>;
-}
-
-export interface RegisterInboxOptions {
-  /** Override the cursor-store filename (tests). */
-  storeFileName?: string;
-  /** Skip the initial seed poll (tests that drive polling manually). */
-  skipInitialPoll?: boolean;
-  /** Register the built-in slack/discord/email adapters (default true). */
-  registerBuiltins?: boolean;
-  /**
-   * Hand polling to a leadership gate instead of starting it here.
-   *
-   * When supplied, register() prepares the store and the handler but does NOT
-   * poll: the callback receives start/stop control and something else decides
-   * when this node is the one that should be fetching. When absent the loops
-   * start immediately, which is the behaviour every existing caller and test
-   * relies on.
-   *
-   * The READ path is never gated. `channels.inbox.list` serves the persisted
-   * feed on every node — a node that is not fetching still answers questions
-   * about what has already arrived.
-   *
-   * Called once PER PROVIDER, with that provider's id and a control that
-   * starts and stops only its loop. Each inbox account is its own surface in
-   * the LAN election, so the machine reading the work Slack account need not
-   * be the machine reading the mailbox — and handing one account over must not
-   * take the others down with it.
-   */
-  gatePolling?: (providerId: string, control: InboxPollingControl) => void;
-}
-
-function registerBuiltinAdapters(): void {
-  registerAdapterFactory(SLACK_PROVIDER_ID, (ctx) => createSlackAdapter(ctx));
-  registerAdapterFactory(DISCORD_PROVIDER_ID, (ctx) => createDiscordAdapter(ctx));
-  registerAdapterFactory(EMAIL_PROVIDER_ID, (ctx) => createEmailAdapter(ctx));
-}
-
-function normalizeInput(body: unknown): { providers?: string[]; limit: number; since?: number } {
-  const input = (body ?? {}) as InboxListInput;
-  const provider = typeof input.provider === 'string' && input.provider.length > 0
-    ? input.provider
-    : undefined;
-  let limit = typeof input.limit === 'number' && Number.isFinite(input.limit)
-    ? Math.floor(input.limit)
-    : DEFAULT_LIMIT;
-  limit = Math.min(Math.max(1, limit), MAX_LIMIT);
-  const since = typeof input.since === 'number' && Number.isFinite(input.since) && input.since >= 0
-    ? Math.floor(input.since)
-    : undefined;
-  return {
-    ...(provider ? { providers: [provider] } : {}),
-    limit,
-    ...(since !== undefined ? { since } : {}),
-  };
-}
-
-/** Map a daemon-internal item onto the SDK CHANNEL_INBOX_ITEM_SCHEMA wire shape. */
-function toWireItem(item: InboundChannelItem): ChannelInboxItem {
-  const wire: ChannelInboxItem = {
-    id: item.id,
-    provider: item.provider,
-    kind: item.kind,
-    from: item.fromDigest,
-    bodyPreview: item.bodyPreview,
-    receivedAt: item.receivedAt,
-    unread: item.unread,
-  };
-  if (item.subjectPreview.length > 0) wire.subject = item.subjectPreview;
-  if (item.routeId != null) wire.routeId = item.routeId;
-  return wire;
-}
-
-/**
- * Bridge the routing surface's profile resolver into the adapter `RouteResolver`
- * seam. Resolution is by provider surface (best-effort wildcard); a resolved
- * profile id is surfaced as the item's routeId binding. Never throws.
- */
-function routeResolverFromRouting(routing: RoutingRegistration): RouteResolver {
-  return ({ provider }) => {
-    try {
-      return routing.resolveProfileId(provider) ?? undefined;
-    } catch {
-      return undefined;
-    }
-  };
-}
-
-/**
- * Register the inbox surface. Attaches the `channels.inbox.list` handler to the
- * SDK catalog and returns an Unregister that detaches it, stops the poller, and
- * closes the store.
- */
-export function registerInboxMethods(
-  ctx: HandlerContext,
-  routing?: RoutingRegistration,
-  options: RegisterInboxOptions = {},
-): Unregister {
-  if (options.registerBuiltins !== false) {
-    registerBuiltinAdapters();
-  }
-
-  const adapterContext: AdapterContext = {
-    credentials: ctx.credentials,
-    logger: ctx.logger,
-    ...(routing ? { resolveRouteId: routeResolverFromRouting(routing) } : {}),
-  };
-  const adapters = buildAdapters(adapterContext);
-  // Retention runs inside the store (age TTL + count cap, at init and then on a
-  // timer). Both hooks carry COUNTS ONLY — no sender ids, subjects or bodies.
-  const store = new InboxCursorStore(ctx.workingDirectory, options.storeFileName, {
-    onSweep: (summary) => {
-      ctx.logger.info('inbox retention sweep reclaimed items', {
-        expired: summary.expired,
-        capped: summary.capped,
-        remaining: summary.remaining,
-      });
-    },
-    onSweepError: (message) => {
-      ctx.logger.warn('inbox retention sweep failed', { error: message });
-    },
-  });
-  const poller = new InboundPoller({ adapters, store, logger: ctx.logger });
-
-  const gated = options.gatePolling !== undefined;
-
-  // Async bootstrap: init store, and (ungated) seed one poll and start loops.
-  // Failures are logged but never thrown out of register() — the handler still
-  // serves the (possibly empty) persisted feed.
-  const ready: Promise<void> = (async () => {
-    await store.init();
-    if (gated) return;
-    if (!options.skipInitialPoll) {
-      await poller.pollOnce();
-    }
-    poller.start();
-  })().catch((error: unknown) => {
-    ctx.logger.error('inbox surface bootstrap failed', {
-      error: summarizeError(error),
-    });
-  });
-
-  const gate = options.gatePolling;
-  if (gate) {
-    // One gate per provider, not one for the poller. Leadership is decided per
-    // inbox account, so each account's loop has to be startable and stoppable
-    // on its own — otherwise handing one account to another machine would stop
-    // fetching for every account this node reads.
-    for (const providerId of poller.providerIds()) {
-      gate(providerId, {
-        start: async () => {
-          // The store must be ready before the first fetch, or the seed poll
-          // would write cursors into an uninitialised store.
-          await ready;
-          if (!options.skipInitialPoll) {
-            await poller.pollProviderOnce(providerId);
-          }
-          poller.startProvider(providerId);
-        },
-        // Synchronous underneath: it clears that provider's interval, so once
-        // it returns no further poll of that account can be scheduled.
-        // Declared async because the gate contract promises "resolves when
-        // consumption has ceased", and a future adapter with an in-flight
-        // request would need to await it.
-        stop: async () => {
-          poller.stopProvider(providerId);
-        },
-      });
-    }
-  }
-
-  const unregisterMethod = registerCatalogHandler<InboxListInput, InboxListOutput>(
-    ctx.catalog,
-    INBOX_LIST_METHOD_ID,
-    async (invocation) => {
-      await ready;
-      const { providers, limit, since } = normalizeInput(invocation.body);
-      const internalItems = store.listItems({
-        ...(providers ? { providers } : {}),
-        ...(since !== undefined ? { since } : {}),
-        limit,
-      });
-      const items = internalItems.map(toWireItem);
-      const total = store.countItems(providers);
-      const truncated = internalItems.length >= limit && total > internalItems.length;
-      const maxReceived = store.maxReceivedAt(providers);
-      const nextSince = Math.max(since ?? 0, maxReceived);
-      const output: InboxListOutput = { items, total, truncated };
-      if (nextSince > 0) output.cursor = String(nextSince);
-      return output;
-    },
-  );
-
-  return () => {
-    try {
-      unregisterMethod();
-    } finally {
-      poller.stop();
-      void store.close();
-    }
-  };
-}

package/src/daemon/handlers/inbox/mapping.ts

@@ -1,192 +0,0 @@
-// ---------------------------------------------------------------------------
-// Pure mapping + redaction helpers shared by every adapter.
-//
-// Rules (from the handoff contract):
-//   - fromDigest  = sha256First(senderExternalId, 16)   (never the raw id)
-//   - bodyPreview = plain-text, PII-stripped, truncated to 500 chars
-//   - subjectPreview <= 200 chars
-// These are pure and deterministic so they are unit-testable in isolation.
-// ---------------------------------------------------------------------------
-
-import { createHash } from 'node:crypto';
-
-export const SUBJECT_PREVIEW_MAX = 200;
-export const BODY_PREVIEW_MAX = 500;
-
-/** First `hexChars` hex chars of the SHA-256 digest of `input` (utf-8). */
-export function sha256First(input: string, hexChars: number): string {
-  const digest = createHash('sha256').update(input, 'utf-8').digest('hex');
-  return digest.slice(0, Math.max(0, hexChars));
-}
-
-/**
- * Digest a sender's external id to a stable 16-hex-char token (the first 8
- * bytes of the SHA-256 digest). The raw id is never emitted.
- */
-export function digestSender(senderExternalId: string): string {
-  return sha256First(senderExternalId, 16);
-}
-
-// PII patterns stripped from body previews before they ever leave the daemon.
-const EMAIL_RE = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g;
-// E.164-ish and common separated phone numbers (>=7 digits with separators).
-const PHONE_RE = /(?:\+?\d[\d\s().-]{6,}\d)/g;
-// Long digit runs that look like card / account numbers (13-19 digits).
-const LONG_NUMBER_RE = /\b\d{13,19}\b/g;
-// IPv4 addresses.
-const IPV4_RE = /\b(?:\d{1,3}\.){3}\d{1,3}\b/g;
-
-// --- Secret / token patterns -----------------------------------------------
-// These must run BEFORE the generic numeric/email scrubbers and are ordered
-// most-specific first so a long opaque secret is never partially redacted.
-//
-// `Authorization: Bearer <token>` / bare `Bearer <token>`.
-const BEARER_RE = /\bBearer\s+[A-Za-z0-9._~+/=-]{8,}/gi;
-// JSON Web Tokens: three base64url segments separated by dots (header.payload.sig).
-const JWT_RE = /\beyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}/g;
-// Slack tokens: xoxb-/xoxp-/xoxa-/xoxr-/xoxs-... and legacy xox*-.
-const SLACK_TOKEN_RE = /\bxox[abeoprs]-[A-Za-z0-9-]{8,}/gi;
-// Common prefixed provider keys: OpenAI sk-/sk-proj-, GitHub gh[poursa]_,
-// Google AIza..., Stripe sk_live_/pk_live_/rk_live_, Slack-app xapp-, AWS AKIA...
-const PREFIXED_KEY_RE =
-  /\b(?:sk-(?:proj-)?[A-Za-z0-9_-]{16,}|gh[poursa]_[A-Za-z0-9]{16,}|AIza[A-Za-z0-9_-]{16,}|(?:sk|pk|rk)_(?:live|test)_[A-Za-z0-9]{16,}|xapp-[A-Za-z0-9-]{8,}|AKIA[A-Z0-9]{16})/g;
-// `token=`, `api_key=`, `access_token: ...`, `secret = ...` style key/value pairs.
-const KV_SECRET_RE =
-  /\b(?:api[_-]?key|access[_-]?token|refresh[_-]?token|client[_-]?secret|secret|token|password|passwd|pwd|authorization|auth)\b\s*[:=]\s*(?:"[^"]*"|'[^']*'|[A-Za-z0-9._~+/=-]{6,})/gi;
-// Generic high-entropy opaque blobs (>=24 chars of base64url/hex) not already
-// caught above — catches raw API keys pasted without a recognizable prefix.
-const OPAQUE_SECRET_RE = /\b[A-Za-z0-9_-]{24,}\b/g;
-
-/**
- * Replace PII and credentials with stable redaction tokens (does not alter the
- * length budget). Secrets/tokens are scrubbed before the email/phone/number
- * passes so an OAuth/bearer/API token can never leak into a preview.
- */
-export function stripPii(input: string): string {
-  return input
-    .replace(BEARER_RE, '[token]')
-    .replace(JWT_RE, '[token]')
-    .replace(SLACK_TOKEN_RE, '[token]')
-    .replace(PREFIXED_KEY_RE, '[token]')
-    .replace(KV_SECRET_RE, (match) => {
-      const sep = match.includes('=') ? '=' : ':';
-      const key = match.slice(0, match.indexOf(sep)).trimEnd();
-      return `${key}${sep}[token]`;
-    })
-    .replace(EMAIL_RE, '[email]')
-    .replace(IPV4_RE, '[ip]')
-    .replace(LONG_NUMBER_RE, '[number]')
-    .replace(PHONE_RE, (match) => {
-      // Avoid eating short numeric tokens that survived LONG_NUMBER_RE; only
-      // redact when there are at least 7 digits.
-      const digits = match.replace(/\D/g, '');
-      return digits.length >= 7 ? '[phone]' : match;
-    })
-    // Sweep any remaining long opaque blob (e.g. a bare API key) last so we do
-    // not clobber the redaction tokens we just inserted.
-    .replace(OPAQUE_SECRET_RE, (match) => (/^[A-Za-z]+$/.test(match) ? match : '[token]'));
-}
-
-// --- Markup / MIME de-structuring ------------------------------------------
-// Email BODY[TEXT] is frequently raw HTML and/or a multipart/MIME payload with
-// boundary lines and Content-* headers. Previews must be human-readable plain
-// text, so we de-MIME (prefer the text/plain part), strip tags, and decode the
-// handful of HTML entities that survive into previews. This is a no-op on text
-// that is already plain.
-const HTML_ENTITIES: Record<string, string> = {
-  '&amp;': '&', '&lt;': '<', '&gt;': '>', '&quot;': '"',
-  '&#39;': "'", '&apos;': "'", '&nbsp;': ' ',
-};
-
-/** True when the text looks like a MIME multipart payload (has boundary lines). */
-function isMultipart(text: string): boolean {
-  return /^--[^\r\n]+\r?\n/m.test(text) && /content-type:/i.test(text);
-}
-
-/**
- * Given a multipart body, return the decoded text/plain part if present,
- * otherwise the text/html part, otherwise the original input. Strips the
- * per-part MIME headers so only the body bytes remain.
- */
-function extractMimePart(text: string): string {
-  const boundaryMatch = /^--([^\r\n]+?)(?:--)?\r?$/m.exec(text);
-  if (!boundaryMatch) return text;
-  const boundary = boundaryMatch[1]!;
-  const parts = text.split(new RegExp(`--${boundary.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?:--)?\r?\n?`));
-  let htmlPart: string | undefined;
-  for (const rawPart of parts) {
-    const split = /\r?\n\r?\n/.exec(rawPart);
-    if (!split) continue;
-    const headers = rawPart.slice(0, split.index);
-    const body = rawPart.slice(split.index + split[0].length);
-    const ctype = /content-type:\s*([^\r\n;]+)/i.exec(headers)?.[1]?.trim().toLowerCase();
-    if (!ctype) continue;
-    if (ctype === 'text/plain') return body.trim();
-    if (ctype === 'text/html' && htmlPart === undefined) htmlPart = body;
-  }
-  return (htmlPart ?? text).trim();
-}
-
-/** Strip stray top-level MIME/Content-* headers from a single-part body. */
-function stripMimeHeaders(text: string): string {
-  return text.replace(
-    /^(?:content-type|content-transfer-encoding|content-disposition|content-id|mime-version|--[^\r\n]+)\b[^\r\n]*\r?\n/gim,
-    '',
-  );
-}
-
-/** Decode the small set of HTML entities that matter for plain-text previews. */
-function decodeEntities(text: string): string {
-  return text
-    .replace(/&amp;|&lt;|&gt;|&quot;|&#39;|&apos;|&nbsp;/gi, (m) => HTML_ENTITIES[m.toLowerCase()] ?? m)
-    .replace(/&#(\d{1,7});/g, (_m, dec: string) => {
-      const code = Number.parseInt(dec, 10);
-      return Number.isFinite(code) ? String.fromCodePoint(code) : _m;
-    });
-}
-
-/**
- * Convert HTML/MIME body text into readable plain text. Drops <script>/<style>
- * blocks entirely, turns block-level tags into spaces, removes all remaining
- * tags, decodes entities, and de-MIMEs multipart payloads. Plain text passes
- * through unchanged (modulo entity decoding).
- */
-export function stripMarkup(input: string): string {
-  let text = input;
-  if (isMultipart(text)) {
-    text = extractMimePart(text);
-  }
-  text = stripMimeHeaders(text);
-  // Drop script/style contents before tag removal so their bodies never leak.
-  text = text.replace(/<(script|style)\b[^>]*>[\s\S]*?<\/\1>/gi, ' ');
-  // Only treat as HTML if there is an actual tag; avoids mangling plain text
-  // that merely contains a stray '<'.
-  if (/<[a-z!/][^>]*>/i.test(text)) {
-    text = text
-      .replace(/<\/?(?:br|p|div|tr|li|h[1-6]|table|ul|ol|blockquote|hr)\b[^>]*>/gi, ' ')
-      .replace(/<[^>]+>/g, '');
-  }
-  return decodeEntities(text);
-}
-
-/** Collapse whitespace and trim — keeps previews single-line and tidy. */
-export function normalizeWhitespace(input: string): string {
-  return input.replace(/\s+/g, ' ').trim();
-}
-
-/** Build a display-safe subject preview (<=200 chars, no PII, single line). */
-export function toSubjectPreview(raw: string | undefined | null): string {
-  const normalized = normalizeWhitespace(stripPii(raw ?? ''));
-  return normalized.slice(0, SUBJECT_PREVIEW_MAX);
-}
-
-/**
- * Build a display-safe body preview (<=500 chars, plain text, PII-stripped,
- * single line). HTML/MIME is de-structured to readable text first so previews
- * of real-world (HTML/multipart) emails never leak tags or MIME headers.
- */
-export function toBodyPreview(raw: string | undefined | null): string {
-  const plain = stripMarkup(raw ?? '');
-  const normalized = normalizeWhitespace(stripPii(plain));
-  return normalized.slice(0, BODY_PREVIEW_MAX);
-}

package/src/daemon/handlers/inbox/poller.ts

@@ -1,212 +0,0 @@
-// ---------------------------------------------------------------------------
-// Inbound provider poller.
-//
-// Runs one setInterval per provider at the provider's own cadence (Slack/
-// Discord 30s, email 60s, others 120s). Each tick:
-//   1. resolves the provider's persisted cursor (nextSince)
-//   2. calls adapter.poll({ since, limit })
-//   3. dedups + persists items into the cursor store (upsert)
-//   4. advances the cursor monotonically to max(receivedAt)
-//   5. records the last per-provider state for channels.inbox.list to report
-//
-// One bad provider can never crash the loop: adapter.poll() resolves with
-// state:'unavailable' instead of rejecting, and any thrown error is caught and
-// downgraded to an 'unavailable' status here.
-// ---------------------------------------------------------------------------
-
-import type { InboundProviderAdapter, ProviderState } from './provider-adapter.ts';
-import type { InboxCursorStore } from './cursor-store.ts';
-import type { HandlerLogger } from '../context.ts';
-import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
-
-export interface ProviderStatus {
-  id: string;
-  state: ProviderState;
-  itemCount: number;
-  error?: string;
-  lastPolledAt?: number;
-}
-
-export interface PollerOptions {
-  adapters: Map<string, InboundProviderAdapter>;
-  store: InboxCursorStore;
-  logger: HandlerLogger;
-  /** Max items fetched per provider per tick. */
-  perProviderLimit?: number;
-  /** Inject a timer factory for tests (defaults to global setInterval). */
-  setIntervalImpl?: typeof setInterval;
-  clearIntervalImpl?: typeof clearInterval;
-}
-
-const DEFAULT_PER_PROVIDER_LIMIT = 50;
-
-export class InboundPoller {
-  private readonly adapters: Map<string, InboundProviderAdapter>;
-  private readonly store: InboxCursorStore;
-  private readonly logger: HandlerLogger;
-  private readonly perProviderLimit: number;
-  private readonly setIntervalImpl: typeof setInterval;
-  private readonly clearIntervalImpl: typeof clearInterval;
-  private readonly timers = new Map<string, ReturnType<typeof setInterval>>();
-  private readonly statuses = new Map<string, ProviderStatus>();
-  private readonly inFlight = new Set<string>();
-  private started = false;
-  /**
-   * Set by stop(), which the surface teardown calls and nothing else — unlike
-   * stopProvider(), which a leadership handover uses and which must stay
-   * resumable. Once the surface is released no interval may be armed again,
-   * including by work that was already in flight: registerInboxMethods() starts
-   * the store bootstrap without awaiting it, so a teardown during that window
-   * would otherwise be followed by a start() that nothing is left to undo.
-   */
-  private released = false;
-
-  constructor(options: PollerOptions) {
-    this.adapters = options.adapters;
-    this.store = options.store;
-    this.logger = options.logger;
-    this.perProviderLimit = options.perProviderLimit ?? DEFAULT_PER_PROVIDER_LIMIT;
-    this.setIntervalImpl = options.setIntervalImpl ?? setInterval;
-    this.clearIntervalImpl = options.clearIntervalImpl ?? clearInterval;
-    for (const id of this.adapters.keys()) {
-      this.statuses.set(id, { id, state: 'empty', itemCount: 0 });
-    }
-  }
-
-  /** Begin per-provider interval loops. Idempotent. Does NOT poll immediately. */
-  start(): void {
-    if (this.released || this.started) return;
-    this.started = true;
-    for (const id of this.adapters.keys()) this.startProvider(id);
-  }
-
-  /**
-   * Begin ONE provider's interval loop. Idempotent.
-   *
-   * Each inbox account is its own surface in the LAN election, so the machine
-   * that reads the work Slack account may not be the machine that reads the
-   * mailbox. A blanket start/stop cannot express that: it would take every
-   * account down to hand one of them over. Everything below is therefore
-   * addressable per provider, and the blanket calls are fan-outs over it.
-   */
-  startProvider(id: string): void {
-    if (this.released || this.timers.has(id)) return;
-    const adapter = this.adapters.get(id);
-    if (!adapter) return;
-    const handle = this.setIntervalImpl(() => {
-      void this.pollProvider(id, adapter);
-    }, adapter.pollIntervalMs);
-    // Do not keep the event loop alive solely for polling (Bun/Node unref).
-    (handle as unknown as { unref?: () => void }).unref?.();
-    this.timers.set(id, handle);
-  }
-
-  /**
-   * Stop ONE provider's interval loop. Idempotent.
-   *
-   * Synchronous underneath — clearing the interval means no further tick can
-   * be scheduled — which is what lets the RESIGN that follows a handoff be an
-   * honest claim that this node has stopped reading that account.
-   */
-  stopProvider(id: string): void {
-    const handle = this.timers.get(id);
-    if (handle === undefined) return;
-    this.clearIntervalImpl(handle);
-    this.timers.delete(id);
-    if (this.timers.size === 0) this.started = false;
-  }
-
-  /** True when this node is polling the given provider right now. */
-  isProviderRunning(id: string): boolean {
-    return this.timers.has(id);
-  }
-
-  /** Every provider this node has an adapter for. */
-  providerIds(): string[] {
-    return [...this.adapters.keys()];
-  }
-
-  /** Run a single poll across all providers now (used on register + tests). */
-  async pollOnce(): Promise<void> {
-    await Promise.all(
-      [...this.adapters.entries()].map(([id, adapter]) => this.pollProvider(id, adapter)),
-    );
-  }
-
-  /** Run a single poll for ONE provider now. Never throws. */
-  async pollProviderOnce(id: string): Promise<void> {
-    const adapter = this.adapters.get(id);
-    if (!adapter) return;
-    await this.pollProvider(id, adapter);
-  }
-
-  /** Poll a single provider, dedup + persist, update status. Never throws. */
-  async pollProvider(id: string, adapter: InboundProviderAdapter): Promise<void> {
-    if (this.inFlight.has(id)) return; // skip overlapping ticks
-    this.inFlight.add(id);
-    const since = this.store.getCursor(id) || undefined;
-    try {
-      const result = await adapter.poll({ since, limit: this.perProviderLimit });
-      if (result.state === 'unavailable') {
-        this.setStatus(id, {
-          id,
-          state: 'unavailable',
-          itemCount: 0,
-          error: result.error ?? 'provider unavailable',
-          lastPolledAt: Date.now(),
-        });
-        return;
-      }
-      const newCount = this.store.upsertItems(result.items);
-      let maxReceived = since ?? 0;
-      for (const item of result.items) {
-        if (item.receivedAt > maxReceived) maxReceived = item.receivedAt;
-      }
-      if (maxReceived > 0) this.store.advanceCursor(id, maxReceived);
-      await this.store.flush();
-      this.setStatus(id, {
-        id,
-        state: result.items.length > 0 ? 'ready' : 'empty',
-        itemCount: newCount,
-        lastPolledAt: Date.now(),
-      });
-    } catch (error) {
-      const message = summarizeError(error);
-      this.logger.warn('inbound poll failed', { provider: id, error: message });
-      this.setStatus(id, {
-        id,
-        state: 'unavailable',
-        itemCount: 0,
-        error: message,
-        lastPolledAt: Date.now(),
-      });
-    } finally {
-      this.inFlight.delete(id);
-    }
-  }
-
-  /** Snapshot of the last known status for each provider. */
-  snapshotStatuses(providerIds?: readonly string[]): ProviderStatus[] {
-    const ids = providerIds && providerIds.length > 0
-      ? providerIds.filter((id) => this.statuses.has(id))
-      : [...this.statuses.keys()];
-    return ids.map((id) => {
-      const status = this.statuses.get(id)!;
-      return { ...status };
-    });
-  }
-
-  /** Release the poller for good: stop every interval loop, and refuse to arm another. Idempotent. */
-  stop(): void {
-    this.released = true;
-    for (const handle of this.timers.values()) {
-      this.clearIntervalImpl(handle);
-    }
-    this.timers.clear();
-    this.started = false;
-  }
-
-  private setStatus(id: string, status: ProviderStatus): void {
-    this.statuses.set(id, status);
-  }
-}