@cloudcli-ai/cloudcli 1.37.1 → 1.37.3

package/server/modules/providers/tests/session-orphan-prune.test.ts

@@ -0,0 +1,107 @@
+import assert from 'node:assert/strict';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import { closeConnection, initializeDatabase, sessionsDb } from '@/modules/database/index.js';
+
+// Each provider synchronizer resolves `os.homedir()` when the registry module is
+// first imported, so HOME has to point at an empty fixture home *before* that
+// import runs. Otherwise the sync pass walks the developer's real ~/.claude.
+const fixtureHome = await mkdtemp(path.join(os.tmpdir(), 'session-prune-home-'));
+const previousHome = process.env.HOME;
+const previousUserProfile = process.env.USERPROFILE;
+process.env.HOME = fixtureHome;
+process.env.USERPROFILE = fixtureHome;
+
+const { sessionSynchronizerService } = await import(
+  '@/modules/providers/services/session-synchronizer.service.js'
+);
+
+process.on('exit', () => {
+  if (previousHome === undefined) {
+    delete process.env.HOME;
+  } else {
+    process.env.HOME = previousHome;
+  }
+  if (previousUserProfile === undefined) {
+    delete process.env.USERPROFILE;
+  } else {
+    process.env.USERPROFILE = previousUserProfile;
+  }
+});
+
+async function withIsolatedDatabase(runTest: (workspace: string) => Promise<void>): Promise<void> {
+  const previousDatabasePath = process.env.DATABASE_PATH;
+  const tempDirectory = await mkdtemp(path.join(os.tmpdir(), 'session-prune-db-'));
+
+  closeConnection();
+  process.env.DATABASE_PATH = path.join(tempDirectory, 'auth.db');
+  await initializeDatabase();
+
+  try {
+    await runTest(tempDirectory);
+  } finally {
+    closeConnection();
+    if (previousDatabasePath === undefined) {
+      delete process.env.DATABASE_PATH;
+    } else {
+      process.env.DATABASE_PATH = previousDatabasePath;
+    }
+    await rm(tempDirectory, { recursive: true, force: true });
+  }
+}
+
+const PROJECT_PATH = '/tmp/session-prune-project';
+
+test('synchronizeSessions drops indexed sessions whose transcript file was deleted', async () => {
+  await withIsolatedDatabase(async (workspace) => {
+    const transcriptDirectory = path.join(workspace, 'transcripts');
+    await mkdir(transcriptDirectory, { recursive: true });
+
+    const livePath = path.join(transcriptDirectory, 'live.jsonl');
+    await writeFile(livePath, '{}\n');
+    const deletedPath = path.join(transcriptDirectory, 'deleted.jsonl');
+
+    sessionsDb.createSession('live-session', 'claude', PROJECT_PATH, 'Live', undefined, undefined, livePath);
+    sessionsDb.createSession('orphan-session', 'claude', PROJECT_PATH, 'Untitled Claude Session', undefined, undefined, deletedPath);
+
+    const result = await sessionSynchronizerService.synchronizeSessions();
+
+    assert.deepEqual(result.failures, []);
+    assert.equal(result.prunedOrphans, 1);
+    assert.equal(sessionsDb.getSessionById('orphan-session'), null);
+    assert.ok(sessionsDb.getSessionById('live-session'), 'a session whose transcript still exists must survive');
+  });
+});
+
+test('synchronizeSessions keeps sessions whose whole transcript directory is missing', async () => {
+  await withIsolatedDatabase(async (workspace) => {
+    // Stands in for an unmounted or not-yet-created home: every transcript
+    // "looks" deleted, so pruning here would wipe the entire index.
+    const unmountedPath = path.join(workspace, 'not-mounted', 'session.jsonl');
+
+    sessionsDb.createSession('unmounted-session', 'claude', PROJECT_PATH, 'Unmounted', undefined, undefined, unmountedPath);
+
+    const result = await sessionSynchronizerService.synchronizeSessions();
+
+    assert.equal(result.prunedOrphans, 0);
+    assert.ok(sessionsDb.getSessionById('unmounted-session'));
+  });
+});
+
+test('synchronizeSessions keeps sessions that have no transcript path yet', async () => {
+  await withIsolatedDatabase(async () => {
+    // App-created rows (jsonl_path NULL until the first provider write) and
+    // OpenCode rows (one shared sqlite file, so jsonl_path stays NULL).
+    sessionsDb.createAppSession('pending-app-session', 'claude', PROJECT_PATH, 'Pending');
+    sessionsDb.createSession('opencode-session', 'opencode', PROJECT_PATH, 'OpenCode', undefined, undefined, null);
+
+    const result = await sessionSynchronizerService.synchronizeSessions();
+
+    assert.equal(result.prunedOrphans, 0);
+    assert.ok(sessionsDb.getSessionById('pending-app-session'));
+    assert.ok(sessionsDb.getSessionById('opencode-session'));
+  });
+});

package/server/modules/providers/tests/session-synchronizer-coalescing.test.ts

@@ -0,0 +1,136 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import { closeConnection, initializeDatabase } from '@/modules/database/index.js';
+import type { IProvider } from '@/shared/interfaces.js';
+
+// Each provider synchronizer resolves `os.homedir()` when the registry module is
+// first imported, so HOME has to point at an empty fixture home *before* that
+// import runs. The registry is stubbed per test, but the import still happens.
+const fixtureHome = await mkdtemp(path.join(os.tmpdir(), 'session-sync-home-'));
+const previousHome = process.env.HOME;
+const previousUserProfile = process.env.USERPROFILE;
+process.env.HOME = fixtureHome;
+process.env.USERPROFILE = fixtureHome;
+
+const { providerRegistry } = await import('@/modules/providers/provider.registry.js');
+const { sessionSynchronizerService } = await import(
+  '@/modules/providers/services/session-synchronizer.service.js'
+);
+
+process.on('exit', () => {
+  if (previousHome === undefined) {
+    delete process.env.HOME;
+  } else {
+    process.env.HOME = previousHome;
+  }
+  if (previousUserProfile === undefined) {
+    delete process.env.USERPROFILE;
+  } else {
+    process.env.USERPROFILE = previousUserProfile;
+  }
+});
+
+async function withIsolatedDatabase(runTest: () => Promise<void>): Promise<void> {
+  const previousDatabasePath = process.env.DATABASE_PATH;
+  const tempDirectory = await mkdtemp(path.join(os.tmpdir(), 'session-sync-db-'));
+
+  closeConnection();
+  process.env.DATABASE_PATH = path.join(tempDirectory, 'auth.db');
+  await initializeDatabase();
+
+  try {
+    await runTest();
+  } finally {
+    closeConnection();
+    if (previousDatabasePath === undefined) {
+      delete process.env.DATABASE_PATH;
+    } else {
+      process.env.DATABASE_PATH = previousDatabasePath;
+    }
+    await rm(tempDirectory, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Installs a single fake provider whose scan only settles when the returned
+ * `release` is called, so a second caller can be observed arriving mid-scan.
+ */
+function stubSlowProvider() {
+  const originalListProviders = providerRegistry.listProviders;
+  let synchronizeCalls = 0;
+  let releaseScan: () => void = () => {};
+  const scanStarted = new Promise<void>((resolveStarted) => {
+    const fakeProvider = {
+      id: 'claude',
+      sessionSynchronizer: {
+        async synchronize() {
+          synchronizeCalls += 1;
+          resolveStarted();
+          await new Promise<void>((resolveScan) => {
+            releaseScan = resolveScan;
+          });
+          return 7;
+        },
+      },
+    } as unknown as IProvider;
+
+    providerRegistry.listProviders = () => [fakeProvider];
+  });
+
+  return {
+    scanStarted,
+    release: () => releaseScan(),
+    getSynchronizeCalls: () => synchronizeCalls,
+    restore: () => {
+      providerRegistry.listProviders = originalListProviders;
+    },
+  };
+}
+
+test('concurrent synchronizeSessions callers share one provider scan', async () => {
+  await withIsolatedDatabase(async () => {
+    const providerStub = stubSlowProvider();
+
+    try {
+      const first = sessionSynchronizerService.synchronizeSessions();
+      await providerStub.scanStarted;
+      // Opening the UI fires /api/projects and /api/projects/archived at once;
+      // the second must join the running scan instead of starting its own.
+      const second = sessionSynchronizerService.synchronizeSessions();
+
+      providerStub.release();
+      const [firstResult, secondResult] = await Promise.all([first, second]);
+
+      assert.equal(providerStub.getSynchronizeCalls(), 1);
+      assert.equal(firstResult.processedByProvider.claude, 7);
+      assert.deepEqual(secondResult, firstResult);
+    } finally {
+      providerStub.restore();
+    }
+  });
+});
+
+test('a synchronizeSessions call after the shared scan settles starts a new scan', async () => {
+  await withIsolatedDatabase(async () => {
+    const providerStub = stubSlowProvider();
+
+    try {
+      const first = sessionSynchronizerService.synchronizeSessions();
+      await providerStub.scanStarted;
+      providerStub.release();
+      await first;
+
+      const second = sessionSynchronizerService.synchronizeSessions();
+      providerStub.release();
+      await second;
+
+      assert.equal(providerStub.getSynchronizeCalls(), 2);
+    } finally {
+      providerStub.restore();
+    }
+  });
+});

package/server/modules/providers/tests/sessions.service.test.ts

@@ -1,5 +1,5 @@
 import assert from 'node:assert/strict';
-import { mkdtemp, rm } from 'node:fs/promises';
+import { appendFile, mkdtemp, rm, writeFile } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import test from 'node:test';
@@ -125,3 +125,69 @@ test('recent sessions map project metadata and preserve database pagination', {
     });
   });
 });
+
+/** One Claude transcript row of user or assistant text, linked by uuid chain. */
+function claudeTextRow(
+  sessionId: string,
+  role: 'user' | 'assistant',
+  text: string,
+  ordinal: number,
+): Record<string, unknown> {
+  return {
+    type: role,
+    uuid: `row-${ordinal}`,
+    parentUuid: ordinal === 0 ? null : `row-${ordinal - 1}`,
+    timestamp: new Date(Date.UTC(2026, 0, 1, 0, 0, ordinal)).toISOString(),
+    sessionId,
+    message: { role, content: [{ type: 'text', text }] },
+  };
+}
+
+test('history pages are sliced from the cached full transcript and see appended rows', { concurrency: false }, async () => {
+  const transcriptDirectory = await mkdtemp(path.join(os.tmpdir(), 'sessions-service-history-'));
+  const sessionId = 'claude-history-cache-session';
+  const transcriptPath = path.join(transcriptDirectory, `${sessionId}.jsonl`);
+
+  try {
+    await withIsolatedDatabase(async () => {
+      const rows = [
+        claudeTextRow(sessionId, 'user', 'one', 0),
+        claudeTextRow(sessionId, 'assistant', 'reply one', 1),
+        claudeTextRow(sessionId, 'user', 'two', 2),
+        claudeTextRow(sessionId, 'assistant', 'reply two', 3),
+      ];
+      await writeFile(transcriptPath, `${rows.map((row) => JSON.stringify(row)).join('\n')}\n`, 'utf8');
+      sessionsDb.createSession(
+        sessionId,
+        'claude',
+        '/tmp/history-cache-project',
+        'History cache conversation',
+        '2026-01-01T00:00:00.000Z',
+        '2026-01-01T00:00:10.000Z',
+        transcriptPath,
+      );
+
+      const page = await sessionsService.fetchHistory(sessionId, { limit: 2, offset: 0 });
+      assert.equal(page.total, 4);
+      assert.equal(page.hasMore, true);
+      assert.deepEqual(page.messages.map((message) => message.content), ['two', 'reply two']);
+
+      // A row appended after the page was cached must appear on the next read.
+      await appendFile(
+        transcriptPath,
+        `${JSON.stringify(claudeTextRow(sessionId, 'user', 'three', 4))}\n`,
+        'utf8',
+      );
+      const refreshed = await sessionsService.fetchHistory(sessionId, { limit: 2, offset: 0 });
+      assert.equal(refreshed.total, 5);
+      assert.deepEqual(refreshed.messages.map((message) => message.content), ['reply two', 'three']);
+
+      // An older page keeps the tail-offset contract while served from cache.
+      const older = await sessionsService.fetchHistory(sessionId, { limit: 2, offset: 2 });
+      assert.deepEqual(older.messages.map((message) => message.content), ['reply one', 'two']);
+      assert.equal(older.hasMore, true);
+    });
+  } finally {
+    await rm(transcriptDirectory, { recursive: true, force: true });
+  }
+});

package/server/modules/providers/tests/skills.test.ts

@@ -69,7 +69,8 @@ const writeClaudePluginCommand = async (
 
 /**
  * This test covers Claude user/project skill folders plus plugin discovery from
- * installed plugin command files and fallback plugin skill files.
+ * installed plugin command files and plugin skill files, including a plugin that
+ * ships both.
  */
 test('providerSkillsService lists claude user, project, and enabled plugin skills', { concurrency: false }, async () => {
   const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'llm-skills-claude-'));
@@ -144,11 +145,19 @@ test('providerSkillsService lists claude user, project, and enabled plugin skill
     );
     await writeSkill(
       path.join(commandPluginInstallPath, 'skills'),
-      'ignored-command-plugin-skill-dir',
-      'ignored-command-plugin-skill',
-      'Command plugin fallback skill should be ignored',
+      'command-plugin-skill-dir',
+      'command-plugin-skill',
+      'Skill shipped beside plugin commands',
     );
     await writeClaudePluginManifest(skillPluginInstallPath, 'ExampleSkills');
+    // A commands folder holding nothing this reader takes must not hide the
+    // skills beside it: plugins do ship commands in other agents' formats.
+    await fs.mkdir(path.join(skillPluginInstallPath, 'commands'), { recursive: true });
+    await fs.writeFile(
+      path.join(skillPluginInstallPath, 'commands', 'other-agent.toml'),
+      'description = "Command for another agent"\n',
+      'utf8',
+    );
     await writeSkill(
       path.join(skillPluginInstallPath, 'skills'),
       'claude-plugin-dir',
@@ -280,7 +289,14 @@ test('providerSkillsService lists claude user, project, and enabled plugin skill
     assert.equal(pluginCommand?.command, '/Notion:insert-row');
     assert.equal(pluginCommand?.description, 'Insert a Notion database row');
     assert.match(pluginCommand?.sourcePath ?? '', /commands[\\/]insert-row\.md$/);
-    assert.equal(byName.has('ignored-command-plugin-skill'), false);
+    // A plugin that ships commands keeps its skills: the CLI offers both, so
+    // the menu lists both rather than letting the commands folder hide them.
+    const commandPluginSkill = byName.get('command-plugin-skill');
+    assert.equal(commandPluginSkill?.scope, 'plugin');
+    assert.equal(commandPluginSkill?.pluginName, 'Notion');
+    assert.equal(commandPluginSkill?.pluginId, 'notion@notion-marketplace');
+    assert.equal(commandPluginSkill?.command, '/Notion:command-plugin-skill');
+    assert.equal(commandPluginSkill?.description, 'Skill shipped beside plugin commands');
 
     const pluginSkill = byName.get('claude-plugin');
     assert.equal(pluginSkill?.scope, 'plugin');

package/server/modules/scheduled-messages/index.ts

@@ -0,0 +1,8 @@
+// The HTTP surface for scheduling a message to a session, mounted by the app.
+export { default as scheduledMessagesRoutes } from './scheduled-messages.routes.js';
+
+// The timer that sends them, started and stopped with the server.
+export {
+  initializeScheduledMessageDispatcher,
+  closeScheduledMessageDispatcher,
+} from './services/scheduled-message-dispatcher.service.js';

package/server/modules/scheduled-messages/scheduled-messages.routes.ts

@@ -0,0 +1,68 @@
+import express from 'express';
+import type { Request, Response } from 'express';
+
+import { scheduledMessagesService } from '@/modules/scheduled-messages/services/scheduled-messages.service.js';
+import { AppError, asyncHandler, createApiSuccessResponse } from '@/shared/utils.js';
+
+type AuthenticatedRequest = Request & { user?: { id?: number | string } };
+
+function readUserId(request: Request): number {
+  const userId = Number((request as AuthenticatedRequest).user?.id);
+  if (!Number.isInteger(userId)) {
+    throw new AppError('Authenticated user is required.', {
+      code: 'USER_REQUIRED',
+      statusCode: 401,
+    });
+  }
+  return userId;
+}
+
+function readString(value: unknown, field: string): string {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new AppError(`${field} is required.`, {
+      code: 'INVALID_REQUEST_BODY',
+      statusCode: 400,
+    });
+  }
+  return value;
+}
+
+const router = express.Router();
+
+router.get(
+  '/',
+  asyncHandler(async (req: Request, res: Response) => {
+    const sessionId = typeof req.query.sessionId === 'string' ? req.query.sessionId : '';
+    const userId = readUserId(req);
+    res.json(createApiSuccessResponse(
+      sessionId
+        ? scheduledMessagesService.listForSession(userId, sessionId)
+        : scheduledMessagesService.listPending(userId),
+    ));
+  }),
+);
+
+router.post(
+  '/',
+  asyncHandler(async (req: Request, res: Response) => {
+    const body = (req.body ?? {}) as Record<string, unknown>;
+    const result = scheduledMessagesService.schedule({
+      userId: readUserId(req),
+      sessionId: readString(body.sessionId, 'sessionId'),
+      content: readString(body.content, 'content'),
+      options: body.options,
+      scheduledFor: readString(body.scheduledFor, 'scheduledFor'),
+    });
+    res.status(201).json(createApiSuccessResponse(result));
+  }),
+);
+
+router.delete(
+  '/:id',
+  asyncHandler(async (req: Request, res: Response) => {
+    scheduledMessagesService.cancel(readUserId(req), readString(req.params.id, 'id'));
+    res.json(createApiSuccessResponse({ cancelled: true }));
+  }),
+);
+
+export default router;

package/server/modules/scheduled-messages/services/scheduled-message-dispatcher.service.ts

@@ -0,0 +1,203 @@
+import { scheduledMessagesDb, sessionDraftsDb } from '@/modules/database/index.js';
+import type { QueuedSessionMessageRecord, ScheduledMessageRow } from '@/modules/database/index.js';
+import { chatRunRegistry, runDetachedChatTurn } from '@/modules/websocket/index.js';
+import type { ProviderRuntimeGateway } from '@/modules/websocket/index.js';
+
+/**
+ * How often due messages are looked for.
+ *
+ * A minute is the granularity the composer offers, and a claim is indexed on
+ * `(status, scheduled_for)`, so the poll is one cheap query. Anything finer
+ * would buy precision nobody asked for.
+ */
+const POLL_INTERVAL_MS = 30_000;
+
+let pollTimer: ReturnType<typeof setInterval> | null = null;
+let dispatchInFlight = false;
+
+type StoredQueuedMessage = {
+  content: string;
+  options: Record<string, unknown>;
+  attachments: unknown[];
+};
+
+function readOptions(raw: string): Record<string, unknown> {
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+      ? parsed as Record<string, unknown>
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+function readQueuedMessage(value: unknown): StoredQueuedMessage | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return null;
+  }
+  const record = value as Record<string, unknown>;
+  const content = typeof record.content === 'string' ? record.content : '';
+  const attachments = Array.isArray(record.attachments)
+    ? record.attachments
+    : Array.isArray(record.images)
+      ? record.images
+      : [];
+  if (!content.trim() && attachments.length === 0) {
+    return null;
+  }
+  const options = record.options && typeof record.options === 'object' && !Array.isArray(record.options)
+    ? record.options as Record<string, unknown>
+    : {};
+  return { content, options, attachments };
+}
+
+async function sendClaimedQueuedMessage(
+  candidate: QueuedSessionMessageRecord,
+  runtime: ProviderRuntimeGateway,
+): Promise<void> {
+  const message = readQueuedMessage(candidate.queuedMessage);
+  if (!message) {
+    sessionDraftsDb.deleteEmptyDraft(candidate.userId, candidate.sessionId);
+    return;
+  }
+
+  const result = await runDetachedChatTurn(
+    {
+      sessionId: candidate.sessionId,
+      userId: candidate.userId,
+      content: message.content,
+      options: { ...message.options, attachments: message.attachments },
+    },
+    { runtime },
+  );
+
+  // The registry check and run reservation are separate operations. If a run
+  // wins that tiny race, put the turn back so the next poll tries again.
+  if (!result.started && result.error === 'A run was already in progress for this session.') {
+    sessionDraftsDb.restoreQueuedMessage(candidate);
+    return;
+  }
+  sessionDraftsDb.deleteEmptyDraft(candidate.userId, candidate.sessionId);
+}
+
+/** Sends every persisted queued turn whose session is currently idle. */
+export async function dispatchQueuedMessages(runtime: ProviderRuntimeGateway): Promise<number> {
+  const candidates = sessionDraftsDb.listQueuedMessages();
+  let claimed = 0;
+
+  await Promise.all(candidates.map(async (candidate) => {
+    if (chatRunRegistry.isProcessing(candidate.sessionId)) {
+      return;
+    }
+    if (!sessionDraftsDb.claimQueuedMessage(candidate)) {
+      return;
+    }
+    claimed += 1;
+    await sendClaimedQueuedMessage(candidate, runtime);
+  }));
+
+  return claimed;
+}
+
+async function sendClaimedMessage(
+  row: ScheduledMessageRow,
+  runtime: ProviderRuntimeGateway,
+): Promise<void> {
+  try {
+    const result = await runDetachedChatTurn(
+      {
+        sessionId: row.session_id,
+        userId: row.user_id,
+        content: row.content,
+        options: readOptions(row.options),
+        // The user picked this time on purpose; a run that happens to be going
+        // is aborted so the scheduled message lands when it was due, instead
+        // of being recorded as "not sent — session was busy".
+        interruptActiveRun: true,
+      },
+      { runtime },
+    );
+
+    // Recorded rather than retried, and recorded whether the run never started
+    // (deleted session, unavailable provider) or started and then failed.
+    // Silently dropping a message the user scheduled is worse than telling
+    // them it did not go.
+    if (!result.started || result.error) {
+      scheduledMessagesDb.markFailed(row.id, result.error ?? 'The session was unavailable when this was due.');
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    scheduledMessagesDb.markFailed(row.id, message);
+  }
+}
+
+/**
+ * Sends every message whose time has come.
+ *
+ * Exported so a test can drive one pass without waiting on the timer.
+ */
+export async function dispatchDueScheduledMessages(
+  runtime: ProviderRuntimeGateway,
+  now: Date = new Date(),
+): Promise<number> {
+  // Claimed before any of them runs, so a long turn cannot let the next poll
+  // pick the same message up again.
+  const due = scheduledMessagesDb.claimDue(now);
+  if (due.length === 0) {
+    return 0;
+  }
+
+  // Sequentially: a session can only have one run at a time, and two due
+  // messages for the same session must not race each other into it.
+  for (const row of due) {
+    await sendClaimedMessage(row, runtime);
+  }
+
+  return due.length;
+}
+
+/**
+ * Starts the poll that sends scheduled messages.
+ *
+ * The schedule lives in the database, so a message stays scheduled across a
+ * restart and one that came due while the server was down is sent on the first
+ * poll after it comes back, rather than being skipped.
+ */
+export function initializeScheduledMessageDispatcher(runtime: ProviderRuntimeGateway): void {
+  if (pollTimer) {
+    return;
+  }
+
+  const poll = () => {
+    // A pass that overruns the interval must not be started again underneath
+    // itself; the claim is transactional but the runs are not.
+    if (dispatchInFlight) {
+      return;
+    }
+    dispatchInFlight = true;
+    void dispatchDueScheduledMessages(runtime)
+      .then(() => dispatchQueuedMessages(runtime))
+      .catch((error: unknown) => {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error('[ScheduledMessages] Dispatch pass failed', { error: message });
+      })
+      .finally(() => {
+        dispatchInFlight = false;
+      });
+  };
+
+  pollTimer = setInterval(poll, POLL_INTERVAL_MS);
+  // Never keep the process alive just to poll for scheduled messages.
+  pollTimer.unref?.();
+
+  // Catch up on anything that came due while the server was not running.
+  poll();
+}
+
+export function closeScheduledMessageDispatcher(): void {
+  if (pollTimer) {
+    clearInterval(pollTimer);
+    pollTimer = null;
+  }
+}