@pellux/goodvibes-daemon 1.28.0

package/src/daemon/webui-command.ts

@@ -0,0 +1,339 @@
+// ---------------------------------------------------------------------------
+// webui-command.ts — `goodvibes-daemon webui enable|disable|status`.
+//
+// WHAT THIS IS FOR
+//
+// The browser operator surface ships as a built bundle of static files, not as a
+// fourth binary and not as a fourth service. The daemon already knows how to
+// serve such a directory: with `controlPlane.webui.serve` on, its own HTTP
+// router answers `/` from `controlPlane.webui.bundleDir` and falls back to
+// index.html for app routes. So installing the web UI is two config writes and
+// a directory on disk — and this is the command that makes those writes, so the
+// curl installer does not have to know the key names, the file format, or which
+// of the three settings tiers a daemon-owned key belongs in. Same reason
+// `provision-wake-model` exists: the installer runs the binary it just placed
+// and the one implementation owns the details.
+//
+// WHERE IT IS SERVED, AND WHY THE URL SAYS WHAT IT SAYS
+//
+// The bundle is served BY THE CONTROL-PLANE LISTENER, same origin as the API
+// (that is the whole point — a same-origin bundle makes the browser's
+// same-origin policy a non-issue and needs no CORS allowlist). So the URL that
+// opens the web UI is the control-plane origin: `http://<host>:<controlPlane.port>`,
+// not `web.port`. `web.port` is the surface's DECLARED endpoint, used for links
+// and for `tailscale serve`; nothing binds it. This command therefore reports —
+// and, when it is still sitting on the shipped placeholder, writes —
+// `web.publicBaseUrl` as the origin that actually answers, so the printed URL,
+// the pairing deep link and the running server all agree.
+//
+// EXPOSURE IS NEVER WIDENED AS A SIDE EFFECT
+//
+// `enable` turns serving on and names the bundle. It does not touch the
+// listener's host mode in either direction, so a fresh install serves the web UI
+// on loopback (the shipped `controlPlane.hostMode` default) and a host already
+// deliberately bound to the LAN keeps that binding. Widening is its own explicit
+// act: `--lan`. Narrowing back is `--loopback`. Both are stated in the receipt.
+// ---------------------------------------------------------------------------
+
+import { isAbsolute, join, resolve } from 'node:path';
+import { existsSync, statSync } from 'node:fs';
+import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+import { resolveRuntimeEndpointBinding } from '@pellux/goodvibes-terminal-shell';
+import { probeStableHostInputs, stableUrlHostForBindHost, type StableHostInputs } from '@pellux/goodvibes-sdk/platform/pairing';
+
+/** The shipped `web.publicBaseUrl` placeholder — a port nothing binds. */
+const SHIPPED_PUBLIC_BASE_URL = 'http://127.0.0.1:3423';
+
+export interface WebuiCommandResult {
+  readonly exitCode: number;
+  readonly lines: readonly string[];
+}
+
+export interface WebuiCommandDeps {
+  /** Reads and writes the daemon-owned `controlPlane.*` / `web.*` keys. */
+  readonly configManager: Pick<ConfigManager, 'get' | 'set'>;
+  /** True when the path names a directory. Injected in tests. */
+  readonly directoryExists?: ((path: string) => boolean) | undefined;
+  /** True when the path names a readable file. Injected in tests. */
+  readonly fileExists?: ((path: string) => boolean) | undefined;
+  /** Resolves a possibly-relative path against this base. Defaults to the cwd. */
+  readonly baseDirectory?: string | undefined;
+  /** Stable-name probe for the LAN origin. Injected in tests so nothing shells out. */
+  readonly probeStableHost?: (() => StableHostInputs) | undefined;
+}
+
+type Posture = 'lan' | 'loopback' | 'unchanged';
+
+interface ParsedWebuiArgs {
+  readonly subcommand: 'enable' | 'disable' | 'status';
+  readonly bundleDir: string | undefined;
+  readonly posture: Posture;
+  readonly errors: readonly string[];
+}
+
+function parseWebuiArgs(argv: readonly string[]): ParsedWebuiArgs {
+  const errors: string[] = [];
+  let subcommand: 'enable' | 'disable' | 'status' = 'status';
+  let bundleDir: string | undefined;
+  let lan = false;
+  let loopback = false;
+  let sawSubcommand = false;
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index] ?? '';
+    if (arg === '--lan') {
+      lan = true;
+      continue;
+    }
+    if (arg === '--loopback') {
+      loopback = true;
+      continue;
+    }
+    if (arg === '--bundle-dir') {
+      const value = argv[index + 1];
+      if (value === undefined || value.startsWith('-')) {
+        errors.push('--bundle-dir needs a directory path');
+        continue;
+      }
+      bundleDir = value;
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith('--bundle-dir=')) {
+      const value = arg.slice('--bundle-dir='.length);
+      if (!value) {
+        errors.push('--bundle-dir needs a directory path');
+        continue;
+      }
+      bundleDir = value;
+      continue;
+    }
+    if (arg.startsWith('-')) {
+      errors.push(`unknown option: ${arg}`);
+      continue;
+    }
+    if (sawSubcommand) {
+      errors.push(`unexpected argument: ${arg}`);
+      continue;
+    }
+    sawSubcommand = true;
+    if (arg === 'enable' || arg === 'disable' || arg === 'status') {
+      subcommand = arg;
+    } else {
+      errors.push(`unknown subcommand: ${arg} (expected enable, disable or status)`);
+    }
+  }
+
+  if (lan && loopback) {
+    errors.push('--lan and --loopback ask for opposite things; pass one of them');
+  }
+  const posture: Posture = lan ? 'lan' : loopback ? 'loopback' : 'unchanged';
+  return { subcommand, bundleDir, posture, errors };
+}
+
+function readString(config: Pick<ConfigManager, 'get'>, key: 'controlPlane.webui.bundleDir' | 'web.publicBaseUrl' | 'web.staticAssetsDir'): string {
+  const raw = config.get(key);
+  return typeof raw === 'string' ? raw.trim() : '';
+}
+
+/**
+ * The origin a browser opens to reach the web UI: the CONTROL-PLANE binding,
+ * because that is the listener serving the bundle. A wildcard bind resolves
+ * through the stable-name ladder (tailscale name, then `<host>.local`, then the
+ * routed address) so the printed URL survives a DHCP lease change where it can.
+ */
+function servingOrigin(
+  config: Pick<ConfigManager, 'get'>,
+  probe: () => StableHostInputs,
+): { readonly origin: string; readonly loopback: boolean; readonly recognized: boolean } {
+  const binding = resolveRuntimeEndpointBinding(config, 'controlPlane');
+  const resolved = stableUrlHostForBindHost(binding.host, probe);
+  const loopback = resolved.host === '127.0.0.1' || resolved.host === 'localhost' || resolved.host === '::1';
+  return { origin: `http://${resolved.host}:${binding.port}`, loopback, recognized: binding.recognized };
+}
+
+/** A bundle directory is usable only when it exists and holds the app shell. */
+function describeBundleProblem(
+  bundleDir: string,
+  directoryExists: (path: string) => boolean,
+  fileExists: (path: string) => boolean,
+): string | null {
+  if (!directoryExists(bundleDir)) {
+    return `no directory at ${bundleDir}`;
+  }
+  if (!fileExists(join(bundleDir, 'index.html'))) {
+    return `${bundleDir} holds no index.html, so it is not a built web UI bundle`;
+  }
+  return null;
+}
+
+function postureLines(origin: string, loopback: boolean): string[] {
+  if (loopback) {
+    return [
+      '  reachable from this machine only (the control-plane listener is bound to loopback).',
+      '  To reach it from another device on your network:  goodvibes-daemon webui enable --lan',
+    ];
+  }
+  return [
+    `  reachable from your network at ${origin} — the control-plane listener is bound to all interfaces.`,
+    '  To take it back to this machine only:  goodvibes-daemon webui enable --loopback',
+  ];
+}
+
+/**
+ * Run the command and report it. Never throws for an ordinary refusal — a bad
+ * argument, a missing bundle, an unwritable settings file all come back as an
+ * exit code and lines, because the caller is often an installer reading both.
+ */
+export function runWebuiCommand(argv: readonly string[], deps: WebuiCommandDeps): WebuiCommandResult {
+  const parsed = parseWebuiArgs(argv);
+  if (parsed.errors.length > 0) {
+    return {
+      exitCode: 2,
+      lines: [
+        ...parsed.errors.map((error) => `webui: ${error}`),
+        'Usage: goodvibes-daemon webui [enable|disable|status] [--bundle-dir <dir>] [--lan|--loopback]',
+      ],
+    };
+  }
+
+  const config = deps.configManager;
+  const directoryExists = deps.directoryExists ?? ((path: string) => existsSync(path) && statSync(path).isDirectory());
+  const fileExists = deps.fileExists ?? ((path: string) => existsSync(path) && statSync(path).isFile());
+  const base = deps.baseDirectory ?? process.cwd();
+  const probe = deps.probeStableHost ?? probeStableHostInputs;
+  const absolute = (path: string): string => (isAbsolute(path) ? path : resolve(base, path));
+
+  if (parsed.subcommand === 'status') {
+    return renderStatus(config, { directoryExists, fileExists, absolute, probe });
+  }
+
+  if (parsed.subcommand === 'disable') {
+    try {
+      config.set('controlPlane.webui.serve', false);
+    } catch (error) {
+      return { exitCode: 1, lines: [`webui: could not write settings — ${message(error)}`] };
+    }
+    const kept = readString(config, 'controlPlane.webui.bundleDir');
+    return {
+      exitCode: 0,
+      lines: [
+        'web UI: no longer served by the daemon.',
+        ...(kept ? [`  the bundle is left on disk at ${kept} — 'goodvibes-daemon webui enable' serves it again`] : []),
+        '  Restart the daemon for this to take effect on a running process.',
+      ],
+    };
+  }
+
+  // enable
+  const requested = parsed.bundleDir ?? readString(config, 'controlPlane.webui.bundleDir');
+  if (!requested) {
+    return {
+      exitCode: 2,
+      lines: [
+        'webui: no bundle directory to serve.',
+        '  Pass one:  goodvibes-daemon webui enable --bundle-dir <dir>',
+      ],
+    };
+  }
+  const bundleDir = absolute(requested);
+  const problem = describeBundleProblem(bundleDir, directoryExists, fileExists);
+  if (problem) {
+    return {
+      exitCode: 1,
+      lines: [
+        `webui: refusing to serve ${bundleDir} — ${problem}.`,
+        '  Nothing was changed.',
+      ],
+    };
+  }
+
+  try {
+    config.set('controlPlane.webui.bundleDir', bundleDir);
+    config.set('controlPlane.webui.serve', true);
+    config.set('web.enabled', true);
+    if (parsed.posture === 'lan') {
+      config.set('controlPlane.hostMode', 'network');
+      config.set('web.hostMode', 'network');
+    } else if (parsed.posture === 'loopback') {
+      config.set('controlPlane.hostMode', 'local');
+      config.set('web.hostMode', 'local');
+    }
+  } catch (error) {
+    return { exitCode: 1, lines: [`webui: could not write settings — ${message(error)}`] };
+  }
+
+  const serving = servingOrigin(config, probe);
+  const lines: string[] = [
+    `web UI: served by the daemon from ${bundleDir}`,
+    `  ${serving.origin}`,
+  ];
+
+  // The shipped `web.publicBaseUrl` names a port nothing binds. Replace it with
+  // the origin that actually answers so the printed URL, the pairing deep link
+  // and the running server agree. A value the operator chose is left alone.
+  const currentPublic = readString(config, 'web.publicBaseUrl');
+  if (!currentPublic || currentPublic === SHIPPED_PUBLIC_BASE_URL) {
+    try {
+      config.set('web.publicBaseUrl', serving.origin);
+    } catch (error) {
+      lines.push(`  note: could not record web.publicBaseUrl (${message(error)}); links may name a different origin.`);
+    }
+  } else if (currentPublic !== serving.origin) {
+    lines.push(`  note: web.publicBaseUrl is set to ${currentPublic}; links use that, the bundle is served at the URL above.`);
+  }
+
+  if (!serving.recognized) {
+    lines.push('  note: controlPlane.hostMode is not one of local|network|custom — the daemon cannot bind until that is corrected.');
+  }
+  lines.push(...postureLines(serving.origin, serving.loopback));
+  lines.push('  Restart the daemon for this to take effect on a running process.');
+  return { exitCode: 0, lines };
+}
+
+function renderStatus(
+  config: Pick<ConfigManager, 'get'>,
+  deps: {
+    readonly directoryExists: (path: string) => boolean;
+    readonly fileExists: (path: string) => boolean;
+    readonly absolute: (path: string) => string;
+    readonly probe: () => StableHostInputs;
+  },
+): WebuiCommandResult {
+  const serve = config.get('controlPlane.webui.serve') === true;
+  const configured = readString(config, 'controlPlane.webui.bundleDir');
+  const fallback = readString(config, 'web.staticAssetsDir');
+  const source = configured ? 'controlPlane.webui.bundleDir' : fallback ? 'web.staticAssetsDir' : '';
+  const directory = configured || fallback;
+
+  if (!serve) {
+    return {
+      exitCode: 0,
+      lines: [
+        'web UI: not served by this daemon (controlPlane.webui.serve is off).',
+        ...(directory ? [`  a bundle directory is configured (${source}): ${directory}`] : []),
+        '  Serve it:  goodvibes-daemon webui enable --bundle-dir <dir>',
+      ],
+    };
+  }
+
+  const serving = servingOrigin(config, deps.probe);
+  const lines = [`web UI: served by the daemon at ${serving.origin}`];
+  if (!directory) {
+    lines.push('  no bundle directory is configured, so every request falls through to the API routes.');
+  } else {
+    const absoluteDir = deps.absolute(directory);
+    const problem = describeBundleProblem(absoluteDir, deps.directoryExists, deps.fileExists);
+    lines.push(problem ? `  bundle (${source}): ${absoluteDir} — UNUSABLE: ${problem}` : `  bundle (${source}): ${absoluteDir}`);
+  }
+  const currentPublic = readString(config, 'web.publicBaseUrl');
+  if (currentPublic && currentPublic !== serving.origin) {
+    lines.push(`  note: web.publicBaseUrl is ${currentPublic}; links use that, the bundle is served at the URL above.`);
+  }
+  lines.push(...postureLines(serving.origin, serving.loopback));
+  return { exitCode: 0, lines };
+}
+
+function message(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/runtime/boot-tasks.ts

@@ -0,0 +1,110 @@
+import { Notifier } from '@pellux/goodvibes-sdk/platform/integrations';
+import { syncConfiguredServices } from '@/runtime/index.ts';
+import { logger, summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+import { operations } from '@pellux/goodvibes-sdk/platform/runtime';
+const { runBootMemoryFold } = operations;
+import { createDaemonPluginLoaderDeps } from './plugin-composition.ts';
+import type { RuntimeServices } from './runtime-services-types.ts';
+
+/**
+ * The boot steps that belong to the graph rather than to the facade.
+ *
+ * The daemon facade starts the brokers, the automation manager and the memory
+ * store; these are the ones it does not know about because they are this
+ * product's own. A step that only runs in a client's bootstrap instead of
+ * here is a step that never happens for this daemon.
+ *
+ * Every one of them is best-effort: none of them is a reason for the daemon not
+ * to start, and each says so in the log if it fails.
+ */
+export async function runDaemonBootTasks(services: RuntimeServices): Promise<void> {
+  // Fold a legacy per-project memory store into the canonical home-scoped one.
+  // Runs after the facade's memoryStore.init(), is id-keyed and idempotent, and
+  // never deletes the legacy file. The daemon is the only host of the canonical
+  // store now, so if it does not fold, nothing does.
+  await runBootMemoryFold(
+    services.memoryStore,
+    services.memoryEmbeddingRegistry,
+    services.workingDirectory,
+    logger,
+  );
+
+  // Provider health, rate limits and credential state become runtime events
+  // rather than something a caller has to poll for.
+  services.providerRegistry.startWatching(services.runtimeBus);
+
+  // Attach the SAME WebhookNotifier the notification verbs keep live, rather
+  // than a second boot-time-only instance. Attached unconditionally: `send()` is
+  // already a safe no-op with zero URLs configured, and attaching only when URLs
+  // exist at boot is how a URL added later reached some notifications and not
+  // the bus listeners until the next restart.
+  const webhookUrls = (services.configManager.getCategory('notifications') as { webhookUrls?: string[] }).webhookUrls ?? [];
+  if (webhookUrls.length > 0) {
+    services.webhookNotifier.setUrls(webhookUrls);
+    services.runtimeDispatch.syncIntegration({
+      id: 'webhooks',
+      displayName: 'Webhooks',
+      category: 'communication',
+      status: 'healthy',
+      enabled: true,
+      successCount: 0,
+      errorCount: 0,
+      meta: { urlCount: webhookUrls.length },
+    }, 'boot.webhooks');
+  }
+  services.webhookNotifier.attachToRuntimeBus(services.runtimeBus);
+
+  // Outbound delivery queues: attach the notifier to the bus when any queue is
+  // configured, and reflect each queue's health into the integrations read model
+  // so a client can show per-channel delivery state without inventing its own.
+  try {
+    const notifier = await Notifier.fromConfig(services.serviceRegistry);
+    const queueStatuses = notifier.getQueueStatus();
+    if (queueStatuses.length > 0) {
+      notifier.attachToRuntimeBus(services.runtimeBus);
+      for (const queueStatus of queueStatuses) {
+        services.runtimeDispatch.syncIntegration({
+          id: queueStatus.channel,
+          displayName: queueStatus.channel[0]!.toUpperCase() + queueStatus.channel.slice(1),
+          category: 'communication',
+          status: queueStatus.metrics.deadLettered > 0 ? 'degraded' : 'healthy',
+          enabled: true,
+          successCount: queueStatus.metrics.delivered,
+          errorCount: queueStatus.metrics.deadLettered,
+          ...(queueStatus.dlqEntries[0]?.deadAt ? { lastErrorAt: queueStatus.dlqEntries[0].deadAt } : {}),
+          ...(queueStatus.dlqEntries[0]?.finalError ? { lastError: queueStatus.dlqEntries[0].finalError } : {}),
+          meta: {
+            attempts: queueStatus.metrics.totalAttempts,
+            retrying: queueStatus.metrics.retrying,
+            deadLetters: queueStatus.metrics.deadLettered,
+            dlqSize: queueStatus.metrics.dlqSize,
+            sloEnforced: queueStatus.sloEnforced,
+          },
+        }, 'boot.notifier');
+      }
+    }
+  } catch (error) {
+    logger.warn('daemon: notifier queue integration sync failed (non-fatal)', { error: summarizeError(error) });
+  }
+
+  // Configured external services become integration rows too, so "is my Linear
+  // token set" is answerable from the daemon rather than from each client's own
+  // idea of the same question.
+  try {
+    await syncConfiguredServices(services.runtimeDispatch.syncIntegration, services.serviceRegistry);
+  } catch (error) {
+    logger.warn('daemon: configured-service integration sync failed (non-fatal)', { error: summarizeError(error) });
+  }
+
+  // Load the plugins this host can serve. The manager was constructed by the
+  // graph and never initialised, so it could list a plugin directory and never
+  // load anything out of it — `enable` persisted a flag that turned nothing on.
+  // Both hosts read the same directories; each takes the registrations it can
+  // serve (plugin-composition.ts). Best-effort like everything else here: a
+  // plugin that will not load is not a reason for the daemon not to start.
+  try {
+    await services.pluginManager.init(createDaemonPluginLoaderDeps(services));
+  } catch (error) {
+    logger.warn('daemon: plugin load failed (non-fatal)', { error: summarizeError(error) });
+  }
+}

package/src/runtime/cluster-composition.ts

@@ -0,0 +1,124 @@
+/**
+ * cluster-composition.ts — this daemon's seat in the LAN leader election.
+ *
+ * When the same goodvibes install runs more than once on one network — a
+ * laptop and a desktop, or two processes on one machine — every copy
+ * independently reads the shared inbox, so one message is picked up twice and
+ * answered twice. The SDK's cluster coordinator elects exactly one node to be
+ * responsible for inbound consumption; everything else stays warm and silent.
+ *
+ * This file exists because this daemon does NOT get that for free from the
+ * SDK facade. The facade gates the consumers IT owns (Telegram
+ * ingress, the ntfy/Slack/Discord provider runtime), but this repository
+ * composes an inbound consumer of its own — the Slack/Discord/email inbox
+ * poller in daemon/handlers/inbox — and the facade knows nothing about it.
+ * A fix that only landed in the facade would leave the poller double-reading
+ * on exactly the machine this product runs on.
+ *
+ * So this composition builds the ONE coordinator for the process, registers
+ * the inbox poller with it, and hands the same instance to the DaemonServer
+ * (via `DaemonConfig.clusterCoordinator`) so the SDK's consumers ride the same
+ * leadership rather than holding a second, competing election.
+ *
+ * What leadership does NOT gate, here or anywhere: outbound delivery,
+ * sessions, the control plane, the HTTP listener, the UI. A standby node is a
+ * complete goodvibes daemon that simply is not the one reading the inbox.
+ */
+import {
+  ClusterCoordinator,
+  inboxSurface,
+  readClusterSettings,
+  type ClusterConsumerGate,
+  type ClusterTransport,
+} from '@pellux/goodvibes-sdk/platform/cluster';
+import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+import type { ShellPathService } from '@/runtime/index.ts';
+import { logger } from '@pellux/goodvibes-sdk/platform/utils';
+import { GOODVIBES_DAEMON_SURFACE_ROOT } from '../config/surface.ts';
+import { VERSION } from '../version.ts';
+
+/** What an inbound poller must expose to be placed under leadership. */
+export interface GatedPollerControl {
+  /** Begin polling. Must not resolve until polling has actually begun. */
+  start(): Promise<void>;
+  /** Stop polling. Must not resolve until no further poll can run. */
+  stop(): Promise<void>;
+}
+
+/**
+ * Build the process's single coordinator.
+ *
+ * Constructing it is inert: no socket is opened and no state is written until
+ * `start()` runs, so composing a runtime in a test never joins a network.
+ *
+ * The version is THIS BINARY's version, not the SDK package's — the same
+ * distinction daemon/cli.ts already makes for the self-update artifact. It is
+ * the first ranking tier, so getting it wrong would let a stale build hold the
+ * role through an update.
+ */
+export function createClusterComposition(options: {
+  /**
+   * Narrowed to what is actually read, which is exactly what
+   * `readClusterSettings` asks for. The daemon passes a whole ConfigManager;
+   * the handler context carries only this slice, and a test standing in a
+   * minimal config object should not have to fabricate the full fifty-odd
+   * members to compose a coordinator — a cast there would hide a real shape
+   * mismatch rather than document one.
+   */
+  readonly configManager: Pick<ConfigManager, 'getCategory'>;
+  readonly shellPaths: ShellPathService;
+  /**
+   * The datagram transport to coordinate over.
+   *
+   * Supplied by the group layer (cluster-group-composition.ts), which owns the
+   * socket and wraps every election datagram in the group envelope, signed with
+   * the current group key. That is what stops a daemon belonging to somebody
+   * else on the same network from taking part in this election at all.
+   *
+   * Absent — the plain default — means the coordinator opens its own socket and
+   * coordinates with anything that answers on the configured port.
+   */
+  readonly transport?: ClusterTransport | undefined;
+}): ClusterCoordinator {
+  return new ClusterCoordinator({
+    settings: readClusterSettings(options.configManager),
+    version: VERSION,
+    // Surface-scoped, alongside this surface's other durable state: the node
+    // identity is per-surface and must not leak across surface roots.
+    stateDirectory: options.shellPaths.resolveProjectPath(GOODVIBES_DAEMON_SURFACE_ROOT, 'cluster'),
+    logger,
+    ...(options.transport ? { transport: options.transport } : {}),
+  });
+}
+
+/**
+ * ONE inbox provider as a leadership gate.
+ *
+ * One gate per account, not one for the poller. Each inbox account is its own
+ * surface in the election, so this laptop can hold the work Slack account
+ * while the desktop holds the mailbox — and losing one machine moves only the
+ * accounts it was reading. A single gate covering the whole poller could not
+ * express that: it would hand every account over together, and a node with a
+ * credential for only one of them could never take part at all.
+ *
+ * The provider id is the surface's local discriminator and is hashed before it
+ * reaches the network, so what travels is a digest and not an account name.
+ *
+ * No replay cursor is threaded in, and that is deliberate rather than an
+ * omission: the inbox keeps a persisted per-provider cursor of its own
+ * (InboxCursorStore), so a node taking an account over resumes from where the
+ * previous one committed. ntfy needs an explicit `since=` because it has no
+ * server-side per-subscriber cursor; this poller does not.
+ */
+export function inboxPollerGate(providerId: string, control: GatedPollerControl): ClusterConsumerGate {
+  return {
+    id: `inbox-poller:${providerId}`,
+    surface: inboxSurface(providerId),
+    start: async () => {
+      await control.start();
+    },
+    stop: async () => {
+      await control.stop();
+    },
+  };
+}