@pellux/goodvibes-daemon 1.28.0

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

@@ -0,0 +1,221 @@
+// ---------------------------------------------------------------------------
+// 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 composes the answer in ./aggregator.ts — the merged, paginated
+// page plus every provider's standing. Read that file's header for WHY the
+// answer comes from the synced mirror rather than a fresh remote fetch. The
+// redacted `fromDigest` is the only sender value emitted (as `from`); raw
+// sender ids and unredacted bodies never leave the daemon.
+// ---------------------------------------------------------------------------
+
+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 { aggregateInbox, normalizeInboxQuery } from './aggregator.ts';
+import type { InboxListInput, InboxListOutput } from './aggregator.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';
+
+export type {
+  ChannelInboxItem,
+  ChannelInboxProviderStatus,
+  InboxListInput,
+  InboxListOutput,
+} from './aggregator.ts';
+
+/** 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));
+}
+
+/**
+ * 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) => {
+      // The store bootstrap is kicked off without being awaited at register
+      // time, so the first call is where it gets waited on. Waiting here rather
+      // than answering early is what keeps a cold start from reporting an empty
+      // inbox that is only empty because the file is not open yet.
+      await ready;
+      return aggregateInbox(
+        { store, poller },
+        normalizeInboxQuery(invocation.body, invocation.query),
+      );
+    },
+  );
+
+  return () => {
+    try {
+      unregisterMethod();
+    } finally {
+      poller.stop();
+      void store.close();
+    }
+  };
+}

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

@@ -0,0 +1,192 @@
+// ---------------------------------------------------------------------------
+// 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

@@ -0,0 +1,239 @@
+// ---------------------------------------------------------------------------
+// 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;
+  /** NEW items the last poll persisted. Not the provider's stored total. */
+  itemCount: number;
+  error?: string;
+  lastPolledAt?: number;
+  /**
+   * Whether the provider's credentials resolved on the last poll, as the
+   * adapter reported it. Absent until a poll has happened (or when the
+   * credential store itself failed and the adapter could not find out).
+   */
+  configured?: boolean;
+  /**
+   * True once this provider has completed at least one poll on this node.
+   *
+   * A never-polled provider and a polled-and-empty one both hold zero items,
+   * and `channels.inbox.list` must not present the first as the second: on a
+   * node that is not the elected fetcher for an account, "we have not looked"
+   * is the whole truth and "there is nothing" would be a fabrication.
+   */
+  polled: boolean;
+}
+
+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()) {
+      // `polled: false` until a poll actually completes — see ProviderStatus.
+      this.statuses.set(id, { id, state: 'empty', itemCount: 0, polled: false });
+    }
+  }
+
+  /** 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(),
+          ...(result.configured === undefined ? {} : { configured: result.configured }),
+          polled: true,
+        });
+        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(),
+        ...(result.configured === undefined ? {} : { configured: result.configured }),
+        polled: true,
+      });
+    } catch (error) {
+      const message = summarizeError(error);
+      this.logger.warn('inbound poll failed', { provider: id, error: message });
+      // A THROW rather than an honest 'unavailable' result. The adapter got far
+      // enough to run, so the credentials are not the thing that failed —
+      // reporting it as configured is what keeps this out of the
+      // "you never set this up" bucket.
+      this.setStatus(id, {
+        id,
+        state: 'unavailable',
+        itemCount: 0,
+        error: message,
+        lastPolledAt: Date.now(),
+        configured: true,
+        polled: true,
+      });
+    } 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);
+  }
+}