@goodandready/dsh-cron 0.2.2 → 0.2.4

package/lib/index.js

@@ -14,16 +14,48 @@ import {
   pickPatchableFields,
   SCRIPT_CONFIRM_HEADER,
 } from './http-utils.js';
+import { TASK_TYPES, CODE_EXECUTING_TYPES, normalizeTaskType } from './runtimes.js';
+import { resolveTelegramSecrets, resolveCredentialValue } from './secrets.js';
+import { deliverRun, CHANNEL_IDS } from './channels.js';
 
 export const name = '@goodandready/dsh-cron';
-export const inject = ['tools', 'webServer', 'settings', 'llm', 'agents', 'agentDefaultModel'];
+export const inject = ['tools', 'webServer', 'settings', 'llm', 'agents', 'agentDefaultModel', 'credentials'];
 
 export const Config = z.object({
-  botToken: z.string().role('secret').default('').description('Telegram Bot API token used to deliver task reports'),
+  botToken: z.string().role('secret').default('').description('Legacy Telegram Bot API token (prefer botTokenRef with the DSH credentials service)'),
+  botTokenRef: z.string().default('').description('Name of the DSH credential that holds the Telegram bot token'),
   chatId: z.string().default('').description('Telegram chat ID that receives task reports'),
   notifyTelegram: z.boolean().default(false).description('Deliver task reports to Telegram for every task'),
   onlyOnFailure: z.boolean().default(false).description('Deliver reports only for failed runs'),
   kanbanBaseUrl: z.string().default('http://127.0.0.1:3000').description('Base URL of the dsh-kanban HTTP API'),
+  defaultTimezone: z.string().default('').description('Default IANA time zone for schedules (empty = server local)'),
+  maxConcurrent: z.number().default(0).description('Max parallel task runs (0 = unlimited)'),
+  heartbeatUrl: z.string().default('').description('Dead man\'s snitch URL pinged on the heartbeat interval'),
+  heartbeatIntervalSec: z.number().default(0).description('Heartbeat ping interval in seconds (0 = off)'),
+  // --- Delivery channels (#20-#23, #26, #28, #47) ---
+  template: z.string().default('').description('Global notification template; placeholders: {title} {status} {output} {error} {duration} {schedule} {time} {tokens} {cost}'),
+  channelTemplates: z.object({}).default({}).description('Per-channel template overrides keyed by channel id'),
+  deliveryTimeoutMs: z.number().default(15000).description('Per-channel delivery timeout in ms; a slower endpoint is recorded as a failure and does not block other channels or the next tick'),
+  discordWebhookUrl: z.string().default('').description('Discord webhook URL'),
+  slackWebhookUrl: z.string().default('').description('Slack incoming webhook URL'),
+  ntfyUrl: z.string().default('https://ntfy.sh').description('ntfy server base URL'),
+  ntfyTopic: z.string().default('').description('ntfy topic for push notifications'),
+  ntfyTokenRef: z.string().default('').description('Credential name for the ntfy access token'),
+  barkServerUrl: z.string().default('https://api.day.app').description('Bark server base URL'),
+  barkKey: z.string().default('').description('Bark device key'),
+  pushplusTokenRef: z.string().default('').description('Credential name for the PushPlus token'),
+  pushplusUrl: z.string().default('https://www.pushplus.plus/send').description('PushPlus send endpoint (override for a self-hosted proxy)'),
+  smtpHost: z.string().default('').description('SMTP host for email notifications'),
+  smtpPort: z.number().default(587).description('SMTP port'),
+  smtpSecure: z.boolean().default(false).description('Use implicit TLS for SMTP'),
+  smtpUser: z.string().default('').description('SMTP user name'),
+  smtpPasswordRef: z.string().default('').description('Credential name for the SMTP password'),
+  smtpFrom: z.string().default('').description('From address for email notifications'),
+  smtpTo: z.string().default('').description('Comma-separated recipient addresses'),
+  ttsBaseUrl: z.string().default('http://127.0.0.1:3080').description('Base URL of the harness used to reach the dsh-tts speak route'),
+  giteaBaseUrl: z.string().default('').description('Gitea base URL for alert issues'),
+  giteaRepo: z.string().default('').description('Gitea repository (owner/name) for alert issues'),
+  giteaTokenRef: z.string().default('').description('Credential name for the Gitea API token'),
 });
 
 const PATCHABLE_TASK_FIELDS = [
@@ -35,15 +67,67 @@ const PATCHABLE_TASK_FIELDS = [
   'delivery',
   'provider',
   'model',
+  'timezone',
+  'misfirePolicy',
+  'maxRetries',
+  'retryBackoffMs',
+  'permissionPreset',
+  'env',
+  'cwd',
+  'workspaceId',
+  'worktree',
+  'keepWorktree',
+  'httpMethod',
+  'httpUrl',
+  'httpHeaders',
+  'httpBody',
+  'sshTarget',
+  'sshPort',
+  'sshKeyPath',
+  'sshProfileId',
+  'dockerImage',
+  'pythonPath',
+  'nodePath',
+  'skillName',
+  'workflowName',
   'notifyTelegram',
   'onlyOnFailure',
   'timeoutSeconds',
   'overlapPolicy',
   'kanbanMode',
+  'channels',
+  'template',
   'status',
   'oneShot',
 ];
 
+/**
+ * Validate runtime-specific task configuration. Returns an error string or
+ * null when the payload is usable for the given type.
+ */
+export function validateTaskType(type, payload) {
+  const t = normalizeTaskType(type);
+  if (t === 'http') {
+    const raw = String((payload && (payload.httpUrl || payload.prompt)) || '').trim();
+    if (!raw) return 'HTTP tasks require a URL (httpUrl or prompt)';
+    try {
+      // eslint-disable-next-line no-new
+      new URL(raw);
+    } catch {
+      return `Invalid HTTP URL: ${raw}`;
+    }
+  }
+  if (t === 'ssh') {
+    const hasProfile = Boolean(payload && String(payload.sshProfileId || '').trim());
+    const hasTarget = Boolean(payload && String(payload.sshTarget || '').trim());
+    if (!hasProfile && !hasTarget) return 'SSH tasks require sshProfileId (remote-workspace profile) or sshTarget (user@host)';
+  }
+  if (t === 'docker' && !String((payload && payload.dockerImage) || '').trim()) {
+    return 'Docker tasks require dockerImage';
+  }
+  return null;
+}
+
 function sendJson(res, statusCode, data) {
   res.writeHead(statusCode, { 'Content-Type': 'application/json' });
   res.end(JSON.stringify(data));
@@ -66,6 +150,20 @@ async function readBody(req, res) {
   }
 }
 
+/** Settings keys synchronized between the store and the settings service. */
+export const SETTINGS_SYNC_KEYS = [
+  'botToken', 'botTokenRef', 'chatId', 'notifyTelegram', 'onlyOnFailure', 'kanbanBaseUrl',
+  'template', 'channelTemplates', 'deliveryTimeoutMs',
+  'discordWebhookUrl', 'slackWebhookUrl',
+  'ntfyUrl', 'ntfyTopic', 'ntfyTokenRef',
+  'barkServerUrl', 'barkKey',
+  'pushplusTokenRef',
+  'pushplusUrl',
+  'smtpHost', 'smtpPort', 'smtpSecure', 'smtpUser', 'smtpPasswordRef', 'smtpFrom', 'smtpTo',
+  'ttsBaseUrl',
+  'giteaBaseUrl', 'giteaRepo', 'giteaTokenRef',
+];
+
 /**
  * Apply settings writes through the registered settings scope so the core
  * snapshot stays authoritative (#102). Returns null when the settings
@@ -74,7 +172,7 @@ async function readBody(req, res) {
 export async function applySettingsToScope(settingsScope, body) {
   if (!settingsScope || typeof settingsScope.set !== 'function') return null;
   const errors = [];
-  for (const key of ['botToken', 'chatId', 'notifyTelegram', 'onlyOnFailure', 'kanbanBaseUrl']) {
+  for (const key of SETTINGS_SYNC_KEYS) {
     if (!Object.prototype.hasOwnProperty.call(body, key)) continue;
     try {
       await settingsScope.set(key, body[key]);
@@ -86,13 +184,29 @@ export async function applySettingsToScope(settingsScope, body) {
 }
 
 /**
- * Drop values that must never re-enter the store from the client: a masked
- * secret echoed back by the settings UI would overwrite the real token.
+ * Drop values that must never re-enter the store from the client:
+ *
+ * - a masked secret echoed back by the settings UI would overwrite the real
+ *   value (bot token, SMTP password, webhook URLs, Bark key);
+ * - the raw credential keys are refused outright — the *Ref fields are the
+ *   supported way to configure them.
+ *
+ * Applied before both the settings scope and the store, because the scope is
+ * the source of truth and would otherwise persist a raw or masked value.
  */
 export function sanitizeSettingsPayload(body) {
   const payload = Object.assign({}, body);
-  if (typeof payload.botToken === 'string' && (payload.botToken.includes('••') || payload.botToken.includes('****'))) {
-    delete payload.botToken;
+  for (const key of TaskStore.MASKED_SETTING_KEYS) {
+    const val = payload[key];
+    if (typeof val === 'string' && (val.includes('••') || val.includes('****'))) {
+      delete payload[key];
+    }
+  }
+  for (const key of TaskStore.FORBIDDEN_SETTING_KEYS) {
+    if (key in payload) {
+      console.warn(`[dsh-cron] refusing raw secret "${key}" from the client — use a credential reference`);
+      delete payload[key];
+    }
   }
   return payload;
 }
@@ -124,7 +238,11 @@ export function createCronApiHandler(store, scheduler, collection) {
         if (req.method === 'GET') {
           const status = url.searchParams.get('status') || 'all';
           const query = url.searchParams.get('query') || '';
-          const list = store.list({ status, query });
+          const list = store.list({ status, query }).map((t) => ({
+            ...t,
+            running: scheduler.isRunning(t.id),
+            runningSince: scheduler.runningSince(t.id),
+          }));
           const stats = store.getAggregatedStats();
           sendJson(res, 200, { ok: true, tasks: list, recommendations: collection.recommendations, stats });
           return;
@@ -137,9 +255,14 @@ export function createCronApiHandler(store, scheduler, collection) {
             sendJson(res, 400, { ok: false, error: 'Fields title, schedule and prompt are required' });
             return;
           }
-          const taskType = body.type === 'script' ? 'script' : 'llm';
-          if (taskType === 'script' && req.headers[SCRIPT_CONFIRM_HEADER] !== 'script') {
-            sendJson(res, 403, { ok: false, error: 'Creating script tasks over HTTP requires the x-dsh-cron-confirm: script header' });
+          const taskType = normalizeTaskType(body.type);
+          if (CODE_EXECUTING_TYPES.includes(taskType) && req.headers[SCRIPT_CONFIRM_HEADER] !== 'script') {
+            sendJson(res, 403, { ok: false, error: `Creating ${taskType} tasks over HTTP requires the x-dsh-cron-confirm: script header` });
+            return;
+          }
+          const typeError = validateTaskType(taskType, body);
+          if (typeError) {
+            sendJson(res, 400, { ok: false, error: typeError });
             return;
           }
           const parsed = parseScheduleExpression(body.schedule);
@@ -162,6 +285,33 @@ export function createCronApiHandler(store, scheduler, collection) {
             timeoutSeconds: body.timeoutSeconds !== undefined ? Number(body.timeoutSeconds) : (current ? current.timeoutSeconds : 1800),
             overlapPolicy: body.overlapPolicy || (current ? current.overlapPolicy : 'skip'),
             kanbanMode: body.kanbanMode || (current ? current.kanbanMode : 'none'),
+            timezone: body.timezone !== undefined ? String(body.timezone).trim() : (current ? current.timezone : ''),
+            misfirePolicy: ['skip', 'runOnce', 'catchUpAll'].includes(body.misfirePolicy) ? body.misfirePolicy : (current ? (current.misfirePolicy || 'skip') : 'skip'),
+            maxRetries: body.maxRetries !== undefined ? Math.max(0, Number(body.maxRetries) || 0) : (current ? (Number(current.maxRetries) || 0) : 0),
+            retryBackoffMs: body.retryBackoffMs !== undefined ? Math.max(1000, Number(body.retryBackoffMs) || 30000) : (current ? (Number(current.retryBackoffMs) || 30000) : 30000),
+            permissionPreset: ['default', 'read-only', 'workspace-write', 'full'].includes(body.permissionPreset) ? body.permissionPreset : (current ? (current.permissionPreset || 'default') : 'default'),
+            env: body.env && typeof body.env === 'object' ? body.env : (current ? current.env : undefined),
+            cwd: body.cwd !== undefined ? String(body.cwd).trim() : (current ? current.cwd : ''),
+            channels: Array.isArray(body.channels)
+              ? body.channels.filter((c) => CHANNEL_IDS.includes(c))
+              : (current ? current.channels : undefined),
+            template: body.template !== undefined ? String(body.template) : (current ? current.template : ''),
+            workspaceId: body.workspaceId !== undefined ? String(body.workspaceId).trim() : (current ? current.workspaceId : ''),
+            worktree: body.worktree !== undefined ? Boolean(body.worktree) : (current ? Boolean(current.worktree) : false),
+            keepWorktree: body.keepWorktree !== undefined ? Boolean(body.keepWorktree) : (current ? Boolean(current.keepWorktree) : false),
+            httpMethod: body.httpMethod ? String(body.httpMethod).toUpperCase() : (current ? current.httpMethod : 'GET'),
+            httpUrl: body.httpUrl !== undefined ? String(body.httpUrl).trim() : (current ? current.httpUrl : ''),
+            httpHeaders: body.httpHeaders !== undefined ? body.httpHeaders : (current ? current.httpHeaders : undefined),
+            httpBody: body.httpBody !== undefined ? String(body.httpBody) : (current ? current.httpBody : ''),
+            sshProfileId: body.sshProfileId !== undefined ? String(body.sshProfileId).trim() : (current ? current.sshProfileId : ''),
+            sshTarget: body.sshTarget !== undefined ? String(body.sshTarget).trim() : (current ? current.sshTarget : ''),
+            sshPort: body.sshPort !== undefined ? Number(body.sshPort) || 0 : (current ? current.sshPort : 0),
+            sshKeyPath: body.sshKeyPath !== undefined ? String(body.sshKeyPath).trim() : (current ? current.sshKeyPath : ''),
+            dockerImage: body.dockerImage !== undefined ? String(body.dockerImage).trim() : (current ? current.dockerImage : ''),
+            pythonPath: body.pythonPath !== undefined ? String(body.pythonPath).trim() : (current ? current.pythonPath : ''),
+            nodePath: body.nodePath !== undefined ? String(body.nodePath).trim() : (current ? current.nodePath : ''),
+            skillName: body.skillName !== undefined ? String(body.skillName).trim() : (current ? current.skillName : ''),
+            workflowName: body.workflowName !== undefined ? String(body.workflowName).trim() : (current ? current.workflowName : ''),
             oneShot: Boolean(parsed.isOneShot || body.oneShot),
           });
           if (task.status === 'active') {
@@ -236,9 +386,19 @@ export function createCronApiHandler(store, scheduler, collection) {
         if (error) return;
         // Whitelist patchable fields so stats/timestamps stay server-owned (#90)
         const patchData = pickPatchableFields(body, PATCHABLE_TASK_FIELDS);
-        if (patchData.type === 'script' && current.type !== 'script' && req.headers[SCRIPT_CONFIRM_HEADER] !== 'script') {
-          sendJson(res, 403, { ok: false, error: 'Switching a task to the script type over HTTP requires the x-dsh-cron-confirm: script header' });
-          return;
+        if (patchData.type !== undefined) {
+          patchData.type = normalizeTaskType(patchData.type);
+          const switchingToCode = CODE_EXECUTING_TYPES.includes(patchData.type)
+            && !CODE_EXECUTING_TYPES.includes(current.type);
+          if (switchingToCode && req.headers[SCRIPT_CONFIRM_HEADER] !== 'script') {
+            sendJson(res, 403, { ok: false, error: `Switching a task to the ${patchData.type} type over HTTP requires the x-dsh-cron-confirm: script header` });
+            return;
+          }
+          const typeError = validateTaskType(patchData.type, { ...current, ...patchData });
+          if (typeError) {
+            sendJson(res, 400, { ok: false, error: typeError });
+            return;
+          }
         }
         if (patchData.schedule) {
           const parsed = parseScheduleExpression(patchData.schedule);
@@ -278,7 +438,9 @@ export function createCronApiHandler(store, scheduler, collection) {
  * alias pair (#70, #92). Exported for unit tests.
  */
 export function executeCreateTask(store, scheduler, args) {
-  const taskType = args.type === 'script' ? 'script' : 'llm';
+  const taskType = normalizeTaskType(args.type);
+  const typeError = validateTaskType(taskType, args);
+  if (typeError) throw new Error(typeError);
   const parsed = parseScheduleExpression(args.schedule);
   const task = store.set({
     title: args.title,
@@ -294,7 +456,32 @@ export function executeCreateTask(store, scheduler, args) {
     onlyOnFailure: Boolean(args.onlyOnFailure),
     timeoutSeconds: Number(args.timeoutSeconds) || 1800,
     overlapPolicy: args.overlapPolicy || 'skip',
+    timezone: args.timezone ? String(args.timezone).trim() : '',
+    misfirePolicy: ['skip', 'runOnce', 'catchUpAll'].includes(args.misfirePolicy) ? args.misfirePolicy : 'skip',
+    maxRetries: Number(args.maxRetries) > 0 ? Number(args.maxRetries) : 0,
+    retryBackoffMs: Number(args.retryBackoffMs) > 0 ? Number(args.retryBackoffMs) : 30000,
+    permissionPreset: ['default', 'read-only', 'workspace-write', 'full'].includes(args.permissionPreset) ? args.permissionPreset : 'default',
     kanbanMode: args.kanbanMode || 'none',
+    channels: Array.isArray(args.channels) ? args.channels.filter((c) => CHANNEL_IDS.includes(c)) : undefined,
+    template: args.template ? String(args.template) : '',
+    env: args.env && typeof args.env === 'object' ? args.env : undefined,
+    cwd: args.cwd ? String(args.cwd).trim() : '',
+    workspaceId: args.workspaceId ? String(args.workspaceId).trim() : '',
+    worktree: Boolean(args.worktree),
+    keepWorktree: Boolean(args.keepWorktree),
+    httpMethod: args.httpMethod ? String(args.httpMethod).toUpperCase() : 'GET',
+    httpUrl: args.httpUrl ? String(args.httpUrl).trim() : '',
+    httpHeaders: args.httpHeaders,
+    httpBody: args.httpBody !== undefined ? String(args.httpBody) : '',
+    sshProfileId: args.sshProfileId ? String(args.sshProfileId).trim() : '',
+    sshTarget: args.sshTarget ? String(args.sshTarget).trim() : '',
+    sshPort: Number(args.sshPort) || 0,
+    sshKeyPath: args.sshKeyPath ? String(args.sshKeyPath).trim() : '',
+    dockerImage: args.dockerImage ? String(args.dockerImage).trim() : '',
+    pythonPath: args.pythonPath ? String(args.pythonPath).trim() : '',
+    nodePath: args.nodePath ? String(args.nodePath).trim() : '',
+    skillName: args.skillName ? String(args.skillName).trim() : '',
+    workflowName: args.workflowName ? String(args.workflowName).trim() : '',
     oneShot: Boolean(parsed.isOneShot),
   });
   scheduler.scheduleTask(task);
@@ -305,19 +492,44 @@ export function executeCreateTask(store, scheduler, args) {
   };
 }
 
-const createTaskParameters = {
+export const createTaskParameters = {
   title: { type: 'string', description: 'Short task name', required: true },
-  schedule: { type: 'string', description: 'Schedule: cron ("0 9 * * *"), interval ("every 2h") or one-shot ("in 30m", "at: 2026-09-05T15:00:00Z")', required: true },
+  schedule: { type: 'string', description: 'Schedule: cron ("0 9 * * *"), shorthand ("@daily", "@every 30m"), interval ("every 2h") or one-shot ("in 30m", "at: 2026-09-05T15:00:00Z")', required: true },
   prompt: { type: 'string', description: 'Prompt/instruction for the agent at run time', required: true },
-  type: { type: 'string', enum: ['prompt', 'script'], description: 'Task type' },
+  type: { type: 'string', enum: TASK_TYPES, description: 'Task type: llm | script | node | python | http | ssh | docker | skill | workflow' },
   delivery: { type: 'string', enum: ['current', 'isolated'], description: 'Run mode: current (in the current chat) or isolated (separate session)' },
   provider: { type: 'string', description: 'Model provider (optional)' },
   model: { type: 'string', description: 'Model (optional)' },
+  timezone: { type: 'string', description: 'IANA time zone for the schedule, e.g. "Europe/Berlin" (optional, default = server local)' },
   notifyTelegram: { type: 'boolean', description: 'Send the run report to Telegram' },
   onlyOnFailure: { type: 'boolean', description: 'Send reports only for failures' },
   timeoutSeconds: { type: 'number', description: 'Execution time limit in seconds' },
   overlapPolicy: { type: 'string', enum: ['skip', 'queue', 'replace'], description: 'Overlap policy' },
+  misfirePolicy: { type: 'string', enum: ['skip', 'runOnce', 'catchUpAll'], description: 'What to do with a run missed during downtime' },
+  maxRetries: { type: 'number', description: 'Automatic retry attempts on failure (0 = off)' },
+  retryBackoffMs: { type: 'number', description: 'Base backoff between retries in ms, doubled per attempt' },
+  permissionPreset: { type: 'string', enum: ['default', 'read-only', 'workspace-write', 'full'], description: 'Permission preset applied to the task session' },
   kanbanMode: { type: 'string', enum: ['none', 'on_failure', 'always'], description: 'Create a dsh-kanban card for runs' },
+  channels: { type: 'array', items: { type: 'string', enum: CHANNEL_IDS }, description: 'Notification channels for this task; empty = legacy telegram/kanban flags' },
+  template: { type: 'string', description: 'Notification template with {title} {status} {output} {error} {duration} placeholders; empty = built-in text' },
+  env: { type: 'object', additionalProperties: true, description: 'Environment variables for external runtimes (KEY: value); do not store secrets here' },
+  cwd: { type: 'string', description: 'Working directory for the run (external runtimes and agent sessions)' },
+  workspaceId: { type: 'string', description: 'Workspace bound to the task; resolved through the harness' },
+  worktree: { type: 'boolean', description: 'Run code-modifying agent tasks in an isolated git worktree' },
+  keepWorktree: { type: 'boolean', description: 'Keep the created worktree after the run' },
+  nodePath: { type: 'string', description: 'Node.js binary for node tasks (default: the harness runtime)' },
+  pythonPath: { type: 'string', description: 'Python interpreter for python tasks (default: auto-detected venv)' },
+  httpMethod: { type: 'string', description: 'HTTP method for http tasks' },
+  httpUrl: { type: 'string', description: 'URL for http tasks' },
+  httpHeaders: { type: 'object', additionalProperties: true, description: 'Headers for http tasks' },
+  httpBody: { type: 'string', description: 'Request body for http tasks' },
+  sshProfileId: { type: 'string', description: 'dsh-remote-workspace profile id that provides host and credentials' },
+  sshTarget: { type: 'string', description: 'Fallback user@host when no remote-workspace profile is used' },
+  sshPort: { type: 'number', description: 'SSH port (with sshTarget fallback)' },
+  sshKeyPath: { type: 'string', description: 'Private key path (with sshTarget fallback)' },
+  dockerImage: { type: 'string', description: 'Container image for docker tasks' },
+  skillName: { type: 'string', description: 'DSH skill name for skill tasks' },
+  workflowName: { type: 'string', description: 'DSH workflow name for workflow tasks' },
 };
 
 const createTaskOutput = {
@@ -336,7 +548,20 @@ const createTaskOutput = {
 export function apply(ctx, config) {
   const store = new TaskStore();
   const runner = new SessionRunner(ctx);
-  const scheduler = new TaskScheduler(store, (task, opts) => runner.execute(task, opts));
+  const scheduler = new TaskScheduler(store, (task, opts) => runner.execute(task, opts), {
+    maxConcurrent: config && config.maxConcurrent,
+    defaultTimezone: config && config.defaultTimezone,
+    resolveSecrets: (settings) => resolveTelegramSecrets(ctx, settings),
+    deliver: (task, runInfo, settings) => deliverRun({
+      task,
+      runInfo,
+      settings,
+      secrets: {
+        botToken: settings.botToken || '',
+        resolveSecret: (ref) => resolveCredentialValue(ctx, ref),
+      },
+    }),
+  });
 
   // Register settings in the Harness settings service (#71, #102): the scope
   // is the source of truth for the core, scope.watch mirrors values into the
@@ -365,8 +590,21 @@ export function apply(ctx, config) {
 
   scheduler.start();
 
+  // Heartbeat / dead man's snitch (#16): an optional periodic GET ping so an
+  // external monitor can alert when this scheduler stops responding.
+  let heartbeatTimer = null;
+  if (config && config.heartbeatUrl && Number(config.heartbeatIntervalSec) > 0) {
+    const intervalMs = Number(config.heartbeatIntervalSec) * 1000;
+    heartbeatTimer = setInterval(() => {
+      fetch(config.heartbeatUrl, { method: 'GET' }).catch((err) => {
+        console.warn('[dsh-cron] heartbeat ping failed:', err.message);
+      });
+    }, intervalMs);
+  }
+
   ctx.effect(() => {
     return () => {
+      if (heartbeatTimer) clearInterval(heartbeatTimer);
       scheduler.stopAll();
     };
   }, 'dsh-cron: lifecycle');
@@ -466,6 +704,27 @@ export function apply(ctx, config) {
     }
   }), 'dsh-cron: /settings');
 
+  // GET /dsh-cron/heartbeat (#16): liveness probe for external monitors.
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-cron/heartbeat',
+    handler: async (req, res) => {
+      try {
+        const tasks = store.list({ status: 'active' });
+        const lastRuns = tasks.map((t) => t.lastRunAt || 0);
+        sendJson(res, 200, {
+          ok: true,
+          activeTasks: tasks.length,
+          running: scheduler.runningCount(),
+          lastRunAt: lastRuns.length ? Math.max(...lastRuns) : null,
+          serverTime: Date.now(),
+        });
+      } catch (err) {
+        sendJson(res, 500, { ok: false, error: err.message });
+      }
+    }
+  }), 'dsh-cron: /heartbeat');
+
   // POST /dsh-cron/telegram/test
   ctx.effect(() => ctx.webServer.register({
     kind: 'exact',

package/lib/integrations.js

@@ -49,7 +49,8 @@ export async function createKanbanCard({
   column = 'backlog',
   labels = ['cron', 'alert'],
   fetchFn = globalThis.fetch,
-  kanbanBaseUrl = 'http://127.0.0.1:3000'
+  kanbanBaseUrl = 'http://127.0.0.1:3000',
+  signal
 }) {
   try {
     const url = `${kanbanBaseUrl.replace(/\/$/, '')}/dsh-kanban/task`;
@@ -58,6 +59,7 @@ export async function createKanbanCard({
       headers: {
         'Content-Type': 'application/json',
       },
+      signal,
       body: JSON.stringify({
         title,
         body,