@goodandready/dsh-cron 0.2.2 → 0.2.4

package/docs/design/DESIGN.md

@@ -3,7 +3,7 @@
 ## Product / Purpose
 - Назначение: Интегрированный планировщик cron-задач и фоновой автоматизации для DeepSeek Harness. Позволяет запускать агентские сессии по расписанию, выполнять автоматические проверки и предоставлять визуальный интерфейс управления задачами.
 - Аудитория: Пользователи и операторы DeepSeek Harness, автоматизирующие периодические процессы (утренние сводки, проверка тикетов, мониторинг серверов).
-- Статус: Active, публичный npm-пакет @goodandready/dsh-cron (текущая линия 0.1.x → 0.2.0).
+- Статус: Active, публичный npm-пакет @goodandready/dsh-cron (линия 0.2.x).
 
 ## User Surfaces
 - Web/UI:
@@ -11,14 +11,14 @@
   - Кнопка вызова в боковой панели (sidebar-entry) рядом с новой сессией + иконка в шапке сессии (utilities slot).
   - Кнопка «Создать ⌄» с дропдауном:
     - 💬 «Создать с DSH» (запуск интерактивного диалога постановки задачи агенту).
-    - ✏️ «Настроить вручную» (модальная форма: тип, расписание, таймаут, overlap, промпт, модель, уведомления).
+    - ✏️ «Настроить вручную» (модальная форма: тип и параметры рантайма, расписание, таймаут, overlap, промпт, модель, каналы доставки, шаблон сообщения).
   - Табы фильтрации: «Все», «Активные», «На паузе», «Завершённые».
   - Поисковая строка; сводная статистика (активные задачи, запуски, токены, стоимость).
   - Карточки задач: статус-переключатель, название, расписание (человекочитаемое + raw cron), действия (запуск, редактирование, удаление).
   - Блок «Рекомендуемые задачи»: готовые шаблоны (Daily digest, Weekly review, Follow-up monitor) в один клик.
   - Карточка настроек в слоте settings.plugin.item, key = namespace `dsh-cron`; отдельный раздел настроек не используется (#102).
-- LLM Tools: cron_create_task (+ alias cron_schedule_task), cron_list_tasks, cron_pause_task, cron_resume_task, cron_delete_task, cron_run_task.
-- API: HTTP эндпоинты /dsh-cron/* (tasks, models, chat/start, settings, telegram/test, kanban/test, tasks/:id/actions, legacy action/:id/:action). Мутирующие эндпоинты отклоняют cross-origin запросы; script-задачи по HTTP требуют заголовок x-dsh-cron-confirm.
+- LLM Tools: cron_create_task (+ alias cron_schedule_task), cron_list_tasks, cron_pause_task, cron_resume_task, cron_delete_task, cron_run_task. Параметры задачи включают рантайм (`type`), `channels` (список каналов доставки) и `template` (шаблон сообщения).
+- API: HTTP эндпоинты /dsh-cron/* (tasks, models, chat/start, settings, telegram/test, kanban/test, tasks/:id/actions, legacy action/:id/:action). Мутирующие эндпоинты отклоняют cross-origin запросы; script-задачи по HTTP требуют заголовок x-dsh-cron-confirm. Настройки доставки принимаются как плоские ключи (webhook URL, топики, поля SMTP, base URL) и `channelTemplates` — карта шаблонов по каналам.
 - Chat / Slash Commands: отсутствуют (ранее заявленные /cron-команды не были реализованы и удалены из документации; решение 2026-09-09).
 
 ## Visual Direction
@@ -42,8 +42,9 @@
   - CronSidebarButton: кнопка в левом сайдбаре DSH.
   - CronScreen: основной оверлей со списком, табами, статистикой и рекомендациями.
   - CreateDropdown: всплывающее меню выбора способа создания.
-  - ManualTaskModal: модальная форма создания/редактирования (вкладки «Параметры» / «История запусков»).
-  - SettingsModal: настройки Telegram/Kanban с тестами доставки.
+  - ManualTaskModal: модальная форма создания/редактирования (вкладки «Параметры» / «История запусков»); блок каналов доставки — сетка чекбоксов (Telegram, dsh-kanban, Discord, Slack, ntfy, Bark, PushPlus, Email, Voice, Gitea) и поле шаблона сообщения с подсказкой по переменным.
+  - SettingsModal: настройки доставки с тестами; три сворачиваемые секции — «Credentials (references)», «Delivery channels», «Message templates» (шапка-кнопка, aria-expanded, шеврон).
+  - DeliverySettingsForm: общая форма настроек доставки, одна реализация для SettingsModal и CronSettingsCard; секреты вводятся только по имени credential-ссылки.
   - TaskItem: строка задачи с переключателем состояния и действиями.
   - RecommendationCard: плашка с готовым шаблоном.
   - CronSettingsCard: карточка параметров плагина в настройках; свёрнута по умолчанию, шапка-кнопка с шевроном разворачивает тело (aria-expanded), кнопка «Открыть панель задач» — внутри раскрытого тела (решение 2026-09-10, #100).
@@ -57,10 +58,15 @@
 ## User Flows
 1. Создание через DSH-чат: «напоминай каждый день в 9 утра...» → «Создать с DSH» → агент уточняет тип (LLM/NO-LLM), расписание, модель, Silent Rule → после подтверждения вызывает cron_create_task → задача появляется на экране.
 2. Создание вручную: кнопка сайдбара → «Создать ⌄» → «Настроить вручную» → форма → сохранение.
-3. Выполнение по расписанию: croner/таймер one-shot → запуск shell-команды или изолированной агентской сессии → запись в историю → доставка отчёта (Telegram/Kanban по настройкам).
+3. Выполнение по расписанию: croner/таймер one-shot → запуск по выбранному рантайму (агентская сессия, shell, node, python, http, ssh, docker) → запись в историю → доставка отчёта в выбранные каналы (Telegram, Kanban, Discord, Slack, ntfy, Bark, PushPlus, Email, Voice, Gitea) с учётом `onlyOnFailure`.
 4. Разбор инцидента: история запусков в карточке задачи → статус, длительность, вывод/ошибка.
 
 ## Locked Design Decisions
+- 2026-09-11 — Доставка вынесена в отдельный слой: сообщение рендерится шаблоном `{var}` (#25), транспорт — адаптеры каналов с чистым builder'ом payload и инжектируемым fetch, маршрутизатор собирает ошибки каналов и не роняет запуск (#26, #20–#23, #28, #47). Явно выбранные каналы задачи перекрывают legacy-флаги `notifyTelegram`/`kanbanMode`.
+- 2026-09-11 — Доставка не может заблокировать планировщик: каждый канал ограничен таймаутом (`deliveryTimeoutMs`, по умолчанию 15 с), каналы отправляются параллельно, а ошибки (включая таймаут) собираются в `failures`. Причина: `protect: true` в croner пропускал бы следующие тики, пока висит незавершённая доставка (находка независимого review PR #114).
+- 2026-09-11 — Значения с секретом внутри (webhook-URL Discord/Slack, ключ Bark) маскируются при отдаче в браузер, а замаскированное значение, вернувшееся от UI, не перезаписывает сохранённое; сырые credential-ключи отклоняются и в store, и на входе `/dsh-cron/settings`.
+- 2026-09-11 — Секреты доставки хранятся только как credential-ссылки (#51): настройки содержат имя credential, значение резолвится в момент отправки через DSH credentials-сервис с фолбэком на ENV; store отказывается сохранять сырые secret-ключи.
+- 2026-09-11 — Каталог данных плагина: `DSH_DATA_DIR` → `DSH_HOME/data` → `~/.dsh/data`. Причина: изолированный профиль не должен писать в чужой домашний каталог (issue #112, найдено на приёмке в тест-контуре).
 - 2026-09-09 — Пакет надёжности ядра (v0.1.24): буфер shell-задач 10МБ, атомарное сохранение с PID, аудит пропущенных запусков при рестарте (missed), фоновый поллинг UI (8с).
 - 2026-09-03 — Публичный скоуп @goodandready/dsh-cron; оверлей через mountSidebarEntry/mountScreen аналогично dsh-kanban; двойная кнопка «Создать ⌄».
 - 2026-09-09 — Слот карточки настроек: settings.plugin.item с key/namespace `dsh-cron` (совпадение с серверной регистрацией). Причина: контракт слота настроек (#85). Changed 2026-09-10 (#102): settings.section fallback удалён — карточка только во вкладке плагинов.

package/lib/channels.js

@@ -0,0 +1,422 @@
+/**
+ * Delivery channels and router (#26, #20, #21, #22, #23, #47, #28).
+ *
+ * Every adapter is split into a pure payload/request builder (unit-testable
+ * without network) and a thin send step using an injected fetch. The router
+ * decides which channels a run goes to and never throws: failures are
+ * collected so one broken channel cannot hide another.
+ */
+
+import { formatTaskTelegramMessage, sendTelegramMessage } from './telegram.js';
+import { createKanbanCard, shouldCreateKanbanCard } from './integrations.js';
+import { resolveTemplateText, truncateText } from './templates.js';
+
+export const CHANNEL_IDS = ['telegram', 'kanban', 'discord', 'slack', 'ntfy', 'bark', 'pushplus', 'email', 'tts', 'gitea'];
+
+export const CHANNEL_LABELS = {
+  telegram: 'Telegram',
+  kanban: 'dsh-kanban card',
+  discord: 'Discord webhook',
+  slack: 'Slack webhook',
+  ntfy: 'ntfy push',
+  bark: 'Bark push',
+  pushplus: 'PushPlus',
+  email: 'Email (SMTP)',
+  tts: 'Voice via dsh-tts',
+  gitea: 'Gitea issue',
+};
+
+const isFailed = (status) => status === 'error' || status === 'timeout';
+
+/** The message text for a channel: custom template, else built-in defaults. */
+export function messageTextFor(channelId, task, runInfo, settings = {}) {
+  const templates = (settings && settings.channelTemplates) || {};
+  const template = templates[channelId] || settings.template || '';
+  return resolveTemplateText({ template, task, runInfo });
+}
+
+/**
+ * Which channels deliver a given run.
+ * Explicit per-task channels win; otherwise the legacy flags decide.
+ */
+export function resolveChannels(task, settings = {}) {
+  if (Array.isArray(task.channels)) {
+    const explicit = task.channels.filter((id) => CHANNEL_IDS.includes(id));
+    if (explicit.length) return explicit;
+  }
+  const out = [];
+  const notify = task.notifyTelegram !== undefined ? task.notifyTelegram : settings.notifyTelegram;
+  if (notify) out.push('telegram');
+  if ((task.kanbanMode || 'none') !== 'none') out.push('kanban');
+  return out;
+}
+
+/** Failure/only-on-failure filtering, per channel. */
+export function shouldSendToChannel(channelId, task, runInfo, settings = {}) {
+  if (channelId === 'kanban') return shouldCreateKanbanCard(task, runInfo);
+  const onlyOnFail = task.onlyOnFailure !== undefined
+    ? Boolean(task.onlyOnFailure)
+    : Boolean(settings.onlyOnFailure);
+  if (onlyOnFail && !isFailed(runInfo.status)) return false;
+  return true;
+}
+
+// ---------------------------------------------------------------- builders
+
+export function buildDiscordPayload({ text, task, runInfo }) {
+  const failed = isFailed(runInfo.status);
+  return {
+    content: truncateText(text, 1900),
+    embeds: [{
+      title: `${failed ? '❌' : '✅'} ${truncateText(task.title || 'Task', 200)}`,
+      description: truncateText(failed ? (runInfo.error || '') : (runInfo.output || ''), 1900) || undefined,
+      color: failed ? 0xef4444 : 0x10b981,
+      footer: { text: truncateText(task.scheduleText || task.schedule || '', 200) },
+      timestamp: new Date(runInfo.at || Date.now()).toISOString(),
+    }],
+  };
+}
+
+export function buildSlackPayload({ text }) {
+  return { text: truncateText(text, 3000) };
+}
+
+export function buildNtfyRequest({ settings = {}, text, task, token }) {
+  const base = String(settings.ntfyUrl || 'https://ntfy.sh').replace(/\/+$/, '');
+  const topic = String(settings.ntfyTopic || '').trim();
+  if (!topic) throw new Error('ntfyTopic is not configured');
+  const headers = {
+    Title: truncateText(task && task.title ? task.title : 'DSH Cron', 120),
+    Tags: isFailed(task && task.lastStatus) ? 'warning' : 'robot',
+    'Content-Type': 'text/plain; charset=utf-8',
+  };
+  if (token) headers.Authorization = `Bearer ${token}`;
+  return { url: `${base}/${encodeURIComponent(topic)}`, method: 'POST', headers, body: truncateText(text, 4000) };
+}
+
+export function buildBarkRequest({ settings = {}, text, task }) {
+  const server = String(settings.barkServerUrl || 'https://api.day.app').replace(/\/+$/, '');
+  const key = String(settings.barkKey || '').trim();
+  if (!key) throw new Error('barkKey is not configured');
+  const title = truncateText(task && task.title ? task.title : 'DSH Cron', 100);
+  return {
+    url: `${server}/${encodeURIComponent(key)}/${encodeURIComponent(title)}/${encodeURIComponent(truncateText(text, 1200))}`,
+    method: 'GET',
+    headers: {},
+  };
+}
+
+export function buildPushplusRequest({ settings = {}, text, task, token }) {
+  const effective = token || settings.pushplusToken || '';
+  if (!effective) throw new Error('pushplus token is not configured');
+  const url = String(settings.pushplusUrl || 'https://www.pushplus.plus/send').trim();
+  return {
+    url,
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      token: effective,
+      title: truncateText(task && task.title ? task.title : 'DSH Cron', 100),
+      content: truncateText(text, 4000),
+      template: 'markdown',
+    }),
+  };
+}
+
+export function buildGiteaIssuePayload({ task, runInfo }) {
+  const failed = isFailed(runInfo.status);
+  return {
+    title: `${failed ? '[Cron failure]' : '[Cron run]'} ${truncateText(task.title || 'Task', 200)}`,
+    body: [
+      `**Cron task:** ${task.title} (\`${task.id}\`)`,
+      `**Schedule:** ${task.scheduleText || task.schedule || ''}`,
+      `**Status:** ${runInfo.status}`,
+      `**Started at:** ${new Date(runInfo.at || Date.now()).toISOString()}`,
+      runInfo.error ? `\n**Error:**\n\`\`\`\n${truncateText(runInfo.error, 1000)}\n\`\`\`` : '',
+      runInfo.output ? `\n**Output:**\n\`\`\`\n${truncateText(runInfo.output, 1000)}\n\`\`\`` : '',
+    ].filter(Boolean).join('\n\n'),
+    labels: failed ? ['cron', 'bug', 'alert'] : ['cron', 'auto'],
+  };
+}
+
+export function buildEmailMessage({ settings = {}, text, task, runInfo, password, timeoutMs }) {
+  const to = String(settings.smtpTo || '').trim();
+  if (!to) throw new Error('smtpTo is not configured');
+  const from = String(settings.smtpFrom || settings.smtpUser || '').trim();
+  const failed = isFailed(runInfo.status);
+  const bound = Number(timeoutMs) > 0 ? Number(timeoutMs) : DEFAULT_DELIVERY_TIMEOUT_MS;
+  return {
+    from: from || undefined,
+    to,
+    subject: `${failed ? '❌' : '✅'} ${task.title || 'DSH Cron'} — ${runInfo.status}`,
+    text: truncateText(text, 10000),
+    transport: {
+      host: settings.smtpHost || '',
+      port: Number(settings.smtpPort) || 587,
+      secure: Boolean(settings.smtpSecure),
+      auth: settings.smtpUser ? { user: settings.smtpUser, pass: password || '' } : undefined,
+      // Nodemailer has no AbortSignal support: without these a stalled SMTP
+      // server would hold the run (defaults are 2–10 minutes).
+      connectionTimeout: bound,
+      greetingTimeout: bound,
+      socketTimeout: bound,
+    },
+  };
+}
+
+// ------------------------------------------------------------------ sender
+
+export const DEFAULT_DELIVERY_TIMEOUT_MS = 15000;
+
+/**
+ * Bound every outbound request. Without this a single unresponsive endpoint
+ * blocks the remaining channels and, because the run is awaited inside the
+ * croner callback with protect enabled, silently skips subsequent ticks.
+ */
+function deliverySignal(timeoutMs) {
+  const ms = Number(timeoutMs) > 0 ? Number(timeoutMs) : DEFAULT_DELIVERY_TIMEOUT_MS;
+  if (typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function') {
+    return AbortSignal.timeout(ms);
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), ms);
+  if (typeof timer.unref === 'function') timer.unref();
+  return controller.signal;
+}
+
+function isAbort(err) {
+  return Boolean(err) && (err.name === 'AbortError' || err.name === 'TimeoutError');
+}
+
+/**
+ * Hard deadline around one channel's whole work. Signal-based aborts only
+ * help where the callee supports AbortSignal (fetch), while credential
+ * resolution, SMTP and any injected transport ignore it — this is the backstop
+ * that keeps every channel bounded regardless of implementation.
+ */
+function withDeadline(promise, timeoutMs, channelId) {
+  const ms = Number(timeoutMs) > 0 ? Number(timeoutMs) : DEFAULT_DELIVERY_TIMEOUT_MS;
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error(`${channelId}: timed out after ${ms} ms`));
+    }, ms);
+    Promise.resolve(promise).then(
+      (value) => { clearTimeout(timer); resolve(value); },
+      (err) => { clearTimeout(timer); reject(err); },
+    );
+  });
+}
+
+async function sendHttp(fetchFn, request, channelId, signal, timeoutMs) {
+  let res;
+  try {
+    res = await fetchFn(request.url, {
+      method: request.method,
+      headers: request.headers,
+      body: request.body,
+      signal,
+    });
+  } catch (err) {
+    if (isAbort(err)) throw new Error(`${channelId}: timed out after ${timeoutMs} ms`);
+    throw err;
+  }
+  if (!res || !res.ok) {
+    const status = res && res.status ? res.status : 'no-response';
+    throw new Error(`${channelId}: HTTP ${status}`);
+  }
+  return { status: res.status };
+}
+
+/** POST/PUT style JSON request helper used by the tts and gitea channels. */
+async function postJson(http, url, headers, body, channelId, signal, timeoutMs) {
+  let res;
+  try {
+    res = await http(url, { method: 'POST', headers, body, signal });
+  } catch (err) {
+    if (isAbort(err)) throw new Error(`${channelId}: timed out after ${timeoutMs} ms`);
+    throw err;
+  }
+  if (!res || !res.ok) throw new Error(`${channelId}: HTTP ${res && res.status ? res.status : 'no-response'}`);
+  return res.json().catch(() => ({}));
+}
+
+/**
+ * One handler per channel. Each returns a small detail object and throws a
+ * descriptive Error on failure; the router turns that into a failure entry.
+ */
+export const CHANNEL_HANDLERS = {
+  async telegram({ task, runInfo, settings, secrets, http, signal, timeoutMs }) {
+    const botToken = secrets.botToken || '';
+    const chatId = String(settings.chatId || '').trim();
+    if (!botToken || !chatId) throw new Error('telegram: botToken or chatId is not configured');
+    const text = settings.template
+      ? messageTextFor('telegram', task, runInfo, settings)
+      : formatTaskTelegramMessage(task, runInfo);
+    try {
+      await sendTelegramMessage({ botToken, chatId, text, fetchFn: http, signal });
+    } catch (err) {
+      if (isAbort(err)) throw new Error(`telegram: timed out after ${timeoutMs} ms`);
+      throw err;
+    }
+    return { chatId };
+  },
+
+  async kanban({ task, runInfo, settings, http, signal }) {
+    const isErr = isFailed(runInfo.status);
+    const result = await createKanbanCard({
+      title: `${isErr ? '[Cron failure]' : '[Cron completed]'} ${task.title}`,
+      body: buildGiteaIssuePayload({ task, runInfo }).body,
+      board: 'main',
+      column: isErr ? 'backlog' : 'done',
+      labels: isErr ? ['cron', 'bug', 'alert'] : ['cron', 'auto'],
+      kanbanBaseUrl: settings.kanbanBaseUrl || 'http://127.0.0.1:3000',
+      fetchFn: http,
+      signal,
+    });
+    if (!result.success) throw new Error(`kanban: ${result.error}`);
+    return { column: isErr ? 'backlog' : 'done' };
+  },
+
+  async discord({ task, runInfo, settings, http, signal, timeoutMs }) {
+    const url = String(settings.discordWebhookUrl || '').trim();
+    if (!url) throw new Error('discord: discordWebhookUrl is not configured');
+    const payload = buildDiscordPayload({ text: messageTextFor('discord', task, runInfo, settings), task, runInfo });
+    return sendHttp(http, { url, method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(payload) }, 'discord', signal, timeoutMs);
+  },
+
+  async slack({ task, runInfo, settings, http, signal, timeoutMs }) {
+    const url = String(settings.slackWebhookUrl || '').trim();
+    if (!url) throw new Error('slack: slackWebhookUrl is not configured');
+    const payload = buildSlackPayload({ text: messageTextFor('slack', task, runInfo, settings) });
+    return sendHttp(http, { url, method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(payload) }, 'slack', signal, timeoutMs);
+  },
+
+  async ntfy({ task, runInfo, settings, secrets, http, signal, timeoutMs, resolveSecret }) {
+    const token = settings.ntfyTokenRef ? await resolveSecret(settings.ntfyTokenRef) : null;
+    const req = buildNtfyRequest({ settings, text: messageTextFor('ntfy', task, runInfo, settings), task, token });
+    return sendHttp(http, req, 'ntfy', signal, timeoutMs);
+  },
+
+  async bark({ task, runInfo, settings, http, signal, timeoutMs }) {
+    const req = buildBarkRequest({ settings, text: messageTextFor('bark', task, runInfo, settings), task });
+    return sendHttp(http, req, 'bark', signal, timeoutMs);
+  },
+
+  async pushplus({ task, runInfo, settings, secrets, http, signal, timeoutMs, resolveSecret }) {
+    const token = settings.pushplusTokenRef ? await resolveSecret(settings.pushplusTokenRef) : null;
+    const req = buildPushplusRequest({ settings, text: messageTextFor('pushplus', task, runInfo, settings), task, token });
+    return sendHttp(http, req, 'pushplus', signal, timeoutMs);
+  },
+
+  async email({ task, runInfo, settings, deps, resolveSecret, timeoutMs }) {
+    const password = settings.smtpPasswordRef ? await resolveSecret(settings.smtpPasswordRef) : (settings.smtpPassword || '');
+    const message = buildEmailMessage({ settings, text: messageTextFor('email', task, runInfo, settings), task, runInfo, password, timeoutMs });
+    let createTransport = deps.createTransport;
+    if (!createTransport) {
+      try {
+        const mod = await import('nodemailer');
+        createTransport = (mod.default || mod).createTransport;
+      } catch {
+        throw new Error('email: nodemailer is not installed in the harness (install it or use another channel)');
+      }
+    }
+    const transport = createTransport(message.transport);
+    await transport.sendMail({ from: message.from, to: message.to, subject: message.subject, text: message.text });
+    return { to: message.to };
+  },
+
+  async tts({ task, runInfo, settings, http, signal, timeoutMs }) {
+    const base = String(settings.ttsBaseUrl || 'http://127.0.0.1:3080').replace(/\/+$/, '');
+    const payload = { text: truncateText(messageTextFor('tts', task, runInfo, settings), 600) };
+    const data = await postJson(http, `${base}/dsh-tts/speak`, { 'Content-Type': 'application/json' }, JSON.stringify(payload), 'tts', signal, timeoutMs);
+    return { provider: data.provider || 'dsh-tts', tookMs: data.tookMs || null };
+  },
+
+  async gitea({ task, runInfo, settings, http, signal, timeoutMs, resolveSecret }) {
+    const base = String(settings.giteaBaseUrl || '').replace(/\/+$/, '');
+    const repo = String(settings.giteaRepo || '').trim();
+    if (!base || !repo) throw new Error('gitea: giteaBaseUrl and giteaRepo are required');
+    const token = settings.giteaTokenRef ? await resolveSecret(settings.giteaTokenRef) : '';
+    if (!token) throw new Error(`gitea: credential "${settings.giteaTokenRef || ''}" did not resolve`);
+    const payload = buildGiteaIssuePayload({ task, runInfo });
+    const issue = await postJson(
+      http,
+      `${base}/api/v1/repos/${repo}/issues`,
+      { 'Content-Type': 'application/json', Authorization: `token ${token}` },
+      JSON.stringify(payload),
+      'gitea',
+      signal,
+      timeoutMs,
+    );
+    return { number: issue.number || null };
+  },
+};
+
+/**
+ * Deliver one run to one channel.
+ * `resolveSecret(ref)` resolves credential references; `deps.createTransport`
+ * is an injectable nodemailer-compatible factory for tests.
+ */
+export async function sendToChannel({ channelId, task, runInfo, settings = {}, secrets = {}, fetchFn, deps = {}, timeoutMs = DEFAULT_DELIVERY_TIMEOUT_MS }) {
+  const handler = CHANNEL_HANDLERS[channelId];
+  if (!handler) throw new Error(`unknown channel: ${channelId}`);
+  const resolveSecret = typeof secrets.resolveSecret === 'function' ? secrets.resolveSecret : async () => null;
+  const http = fetchFn || globalThis.fetch;
+  const effectiveTimeout = Number(timeoutMs) > 0 ? Number(timeoutMs) : DEFAULT_DELIVERY_TIMEOUT_MS;
+  const work = handler({
+    task,
+    runInfo,
+    settings,
+    secrets,
+    http,
+    deps,
+    resolveSecret,
+    signal: deliverySignal(effectiveTimeout),
+    timeoutMs: effectiveTimeout,
+  });
+  return withDeadline(work, effectiveTimeout, channelId);
+}
+
+/**
+ * Deliver a finished run to every applicable channel.
+ *
+ * Channels are dispatched concurrently and every channel is individually
+ * bounded (AbortSignal for fetch-based channels plus a hard deadline around the
+ * whole handler), so a slow endpoint cannot delay the rest of the report nor
+ * hold the cron callback open. Never throws: per-channel failures are returned
+ * in `failures`.
+ */
+export async function deliverRun({ task, runInfo, settings = {}, secrets = {}, fetchFn, deps = {} }) {
+  const timeoutMs = Number(settings.deliveryTimeoutMs) > 0
+    ? Number(settings.deliveryTimeoutMs)
+    : DEFAULT_DELIVERY_TIMEOUT_MS;
+
+  let channels = [];
+  try {
+    channels = resolveChannels(task, settings);
+  } catch (err) {
+    return { channels: [], delivered: [], skipped: [], failures: [{ channel: 'router', error: (err && err.message) || String(err) }] };
+  }
+
+  const outcomes = await Promise.all(channels.map(async (channelId) => {
+    try {
+      if (!shouldSendToChannel(channelId, task, runInfo, settings)) {
+        return { channel: channelId, skipped: true };
+      }
+      const detail = await sendToChannel({ channelId, task, runInfo, settings, secrets, fetchFn, deps, timeoutMs });
+      return { channel: channelId, detail: detail || null };
+    } catch (err) {
+      return { channel: channelId, error: (err && err.message) || String(err) };
+    }
+  }));
+
+  const delivered = [];
+  const skipped = [];
+  const failures = [];
+  for (const outcome of outcomes) {
+    if (outcome.skipped) skipped.push(outcome.channel);
+    else if (outcome.error) failures.push({ channel: outcome.channel, error: outcome.error });
+    else delivered.push({ channel: outcome.channel, detail: outcome.detail });
+  }
+  return { channels, delivered, skipped, failures };
+}