@cloudcli-ai/cloudcli 1.37.2 → 1.37.4

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

@@ -1,11 +1,15 @@
 import assert from 'node:assert/strict';
-import { mkdtemp, rm } from 'node:fs/promises';
+import { appendFile, 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, projectsDb, sessionsDb } from '@/modules/database/index.js';
+import { providerRegistry } from '@/modules/providers/provider.registry.js';
 import { sessionsService } from '@/modules/providers/services/sessions.service.js';
+import { chatRunRegistry } from '@/modules/websocket/index.js';
+import type { IProvider } from '@/shared/interfaces.js';
+import type { BackgroundTaskSummary } from '@/shared/types.js';
 
 async function withIsolatedDatabase(runTest: () => void | Promise<void>): Promise<void> {
   const previousDatabasePath = process.env.DATABASE_PATH;
@@ -125,3 +129,301 @@ 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 });
+  }
+});
+
+/**
+ * Stands in for the provider registry with one provider per id, each with the
+ * runtime given — the seam through which a runtime's background work reaches
+ * the running-sessions list without an SDK run behind it.
+ */
+async function withProviders(
+  runtimes: Partial<Record<'claude' | 'codex', IProvider['runtime']>>,
+  runTest: () => void | Promise<void>,
+): Promise<void> {
+  const realListProviders = providerRegistry.listProviders;
+  providerRegistry.listProviders = () =>
+    Object.entries(runtimes).map(([id, runtime]) => ({ id, runtime }) as IProvider);
+  try {
+    await runTest();
+  } finally {
+    providerRegistry.listProviders = realListProviders;
+    chatRunRegistry.clearAll();
+  }
+}
+
+/**
+ * Runs `runTest` against a Claude CLI process registry containing exactly
+ * `records`, so the running-sessions tests never read the developer's real
+ * `~/.claude/sessions`.
+ */
+async function withClaudeCliRegistry(
+  records: Array<Record<string, unknown>>,
+  runTest: () => void | Promise<void>,
+): Promise<void> {
+  const homeDirectory = await mkdtemp(path.join(os.tmpdir(), 'claude-cli-registry-'));
+  await mkdir(path.join(homeDirectory, '.claude', 'sessions'), { recursive: true });
+  for (const record of records) {
+    await writeFile(
+      path.join(homeDirectory, '.claude', 'sessions', `${record.pid}.json`),
+      JSON.stringify(record),
+      'utf8',
+    );
+  }
+
+  const realHomedir = os.homedir;
+  (os as unknown as { homedir: () => string }).homedir = () => homeDirectory;
+  try {
+    await runTest();
+  } finally {
+    (os as unknown as { homedir: () => string }).homedir = realHomedir;
+    await rm(homeDirectory, { recursive: true, force: true });
+  }
+}
+
+const task = (taskId: string, startedAt: number): BackgroundTaskSummary => ({
+  taskId,
+  toolUseId: `toolu_${taskId}`,
+  taskType: 'local_agent',
+  description: `Task ${taskId}`,
+  startedAt,
+});
+
+test('running sessions list a session whose background work outlived its turn', { concurrency: false }, async () => {
+  await withIsolatedDatabase(async () => {
+    sessionsDb.createAppSession('held-session', 'claude', '/tmp/running-project');
+    // The turn ran and completed: the registry still holds the finished run.
+    const run = chatRunRegistry.startRun({
+      appSessionId: 'held-session', provider: 'claude', providerSessionId: null, connection: null, userId: null,
+    });
+    assert.ok(run);
+    run.writer.send({ kind: 'text', content: 'launched', sessionId: 'held-session', provider: 'claude' });
+    run.writer.sendComplete({ exitCode: 0 });
+    assert.equal(run.status, 'completed');
+
+    const tasks = [task('late', 2_000), task('early', 1_000)];
+    await withClaudeCliRegistry([], async () => await withProviders(
+      { claude: { run: async () => undefined, abort: () => false, listBackgroundWork: () => [{ sessionId: 'held-session', tasks }] } },
+      async () => {
+        assert.deepEqual(await sessionsService.listRunningSessions(), [{
+          sessionId: 'held-session',
+          provider: 'claude',
+          startedAt: 1_000,
+          lastSeq: run.lastSeq,
+          background: true,
+          canInterrupt: false,
+          tasks,
+        }]);
+        assert.ok(run.lastSeq > 0, 'the finished run still reports its sequence for replay');
+      },
+    ));
+  });
+});
+
+test('running sessions carry their tasks on a chat run that is still going', { concurrency: false }, async () => {
+  await withIsolatedDatabase(async () => {
+    sessionsDb.createAppSession('busy-session', 'claude', '/tmp/running-project');
+    sessionsDb.createAppSession('idle-session', 'codex', '/tmp/running-project');
+    const run = chatRunRegistry.startRun({
+      appSessionId: 'busy-session', provider: 'claude', providerSessionId: null, connection: null, userId: null,
+    });
+    assert.ok(run);
+
+    const tasks = [task('agent', 5_000)];
+    await withClaudeCliRegistry([], async () => await withProviders(
+      {
+        claude: { run: async () => undefined, abort: () => false, listBackgroundWork: () => [{ sessionId: 'busy-session', tasks }] },
+        // A runtime without background work contributes chat runs alone.
+        codex: { run: async () => undefined, abort: () => false },
+      },
+      async () => {
+        const sessions = await sessionsService.listRunningSessions();
+        assert.equal(sessions.length, 1, 'a session with a running chat run is listed once');
+        assert.deepEqual(sessions[0], {
+          sessionId: 'busy-session',
+          provider: 'claude',
+          startedAt: run.startedAt,
+          lastSeq: 0,
+          tasks,
+        });
+      },
+    ));
+  });
+});
+
+test('running sessions with no background work are the chat runs alone', { concurrency: false }, async () => {
+  await withIsolatedDatabase(async () => {
+    sessionsDb.createAppSession('plain-session', 'codex', '/tmp/running-project');
+    const run = chatRunRegistry.startRun({
+      appSessionId: 'plain-session', provider: 'codex', providerSessionId: null, connection: null, userId: null,
+    });
+    assert.ok(run);
+
+    await withClaudeCliRegistry([], async () => await withProviders(
+      { codex: { run: async () => undefined, abort: () => false } },
+      async () => {
+        assert.deepEqual(await sessionsService.listRunningSessions(), [{
+          sessionId: 'plain-session', provider: 'codex', startedAt: run.startedAt, lastSeq: 0,
+        }]);
+      },
+    ));
+  });
+});
+
+test('running sessions report a turn driven by the Claude CLI', { concurrency: false }, async () => {
+  await withIsolatedDatabase(async () => {
+    sessionsDb.createAppSession('cli-session', 'claude', '/tmp/running-project');
+    sessionsDb.assignProviderSessionId('cli-session', 'claude-native-1');
+
+    // `process.pid` is the one pid guaranteed to be alive; omitting procStart
+    // keeps the fixture portable, since the start-time cross-check is Linux-only.
+    await withClaudeCliRegistry(
+      [{ pid: process.pid, sessionId: 'claude-native-1', status: 'busy', entrypoint: 'cli', startedAt: 4_000 }],
+      async () => await withProviders(
+        { claude: { run: async () => undefined, abort: () => false } },
+        async () => {
+          assert.deepEqual(await sessionsService.listRunningSessions(), [{
+            sessionId: 'cli-session',
+            provider: 'claude',
+            startedAt: 4_000,
+            lastSeq: 0,
+            canInterrupt: false,
+            statusText: 'Running in the Claude CLI',
+          }]);
+        },
+      ),
+    );
+  });
+});
+
+test('running sessions ignore registry files a crash left behind', { concurrency: false }, async () => {
+  await withIsolatedDatabase(async () => {
+    sessionsDb.createAppSession('stale-session', 'claude', '/tmp/running-project');
+    sessionsDb.assignProviderSessionId('stale-session', 'claude-native-stale');
+
+    await withClaudeCliRegistry(
+      [
+        // The process is gone: signal 0 cannot find this pid.
+        { pid: 4_194_302, sessionId: 'claude-native-stale', status: 'busy', startedAt: 1_000 },
+        // Alive, but waiting for input rather than producing a response.
+        { pid: process.pid, sessionId: 'claude-native-idle', status: 'idle', startedAt: 2_000 },
+      ],
+      async () => await withProviders(
+        { claude: { run: async () => undefined, abort: () => false } },
+        async () => {
+          assert.deepEqual(await sessionsService.listRunningSessions(), []);
+        },
+      ),
+    );
+  });
+});
+
+test('a CLI turn does not duplicate a session already running a chat run', { concurrency: false }, async () => {
+  await withIsolatedDatabase(async () => {
+    sessionsDb.createAppSession('both-session', 'claude', '/tmp/running-project');
+    sessionsDb.assignProviderSessionId('both-session', 'claude-native-both');
+    const run = chatRunRegistry.startRun({
+      appSessionId: 'both-session', provider: 'claude', providerSessionId: 'claude-native-both', connection: null, userId: null,
+    });
+    assert.ok(run);
+
+    await withClaudeCliRegistry(
+      [{ pid: process.pid, sessionId: 'claude-native-both', status: 'busy', startedAt: 3_000 }],
+      async () => await withProviders(
+        { claude: { run: async () => undefined, abort: () => false } },
+        async () => {
+          const sessions = await sessionsService.listRunningSessions();
+          assert.equal(sessions.length, 1, 'the chat run already covers this session');
+          assert.equal(sessions[0].canInterrupt, undefined, 'the interruptible chat run entry wins');
+        },
+      ),
+    );
+  });
+});
+
+test('an unreadable registry never fails the running-sessions poll', { concurrency: false }, async () => {
+  await withIsolatedDatabase(async () => {
+    sessionsDb.createAppSession('safe-session', 'claude', '/tmp/running-project');
+    sessionsDb.assignProviderSessionId('safe-session', 'claude-native-safe');
+
+    await withClaudeCliRegistry(
+      [{ pid: process.pid, sessionId: 'claude-native-safe', status: 'busy', startedAt: 5_000 }],
+      async () => {
+        // A half-written file sits alongside the good one; it must be skipped
+        // rather than abort the whole poll.
+        await writeFile(path.join(os.homedir(), '.claude', 'sessions', 'broken.json'), '{"pid":', 'utf8');
+        await withProviders(
+          { claude: { run: async () => undefined, abort: () => false } },
+          async () => {
+            const sessions = await sessionsService.listRunningSessions();
+            assert.deepEqual(sessions.map((session) => session.sessionId), ['safe-session']);
+          },
+        );
+      },
+    );
+  });
+});

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,216 @@
+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);
+}
+
+/**
+ * Whether a queued turn has to keep waiting for the session.
+ *
+ * A turn that ends with background work still going (a backgrounded command,
+ * agent or workflow) is marked completed, but its CLI process stays open so
+ * that work can report back. A new turn replaces that process and stops the
+ * work, which is why the composer asks before an interactive send. A queued
+ * turn was promised to go "when this finishes", so it waits for that work too.
+ */
+function isSessionBusy(sessionId: string, runtime: ProviderRuntimeGateway): boolean {
+  return chatRunRegistry.isProcessing(sessionId) || runtime.hasBackgroundWork(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 (isSessionBusy(candidate.sessionId, runtime)) {
+      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;
+  }
+}