@goodandready/dsh-cron 0.3.24 → 0.3.26

package/lib/routes/api-collection.js

@@ -0,0 +1,250 @@
+import { createHash } from 'node:crypto';
+import { parseScheduleExpression } from '../scheduler.js';
+import { normalizeTaskType, CODE_EXECUTING_TYPES, EXTERNAL_RUNTIMES } from '../runtimes.js';
+import { CHANNEL_IDS, unknownChannelIds } from '../channels.js';
+import { MANAGED_BY_CONFIG, configOwnedMessage } from '../config-jobs.js';
+import { sendJson, rejectCrossOrigin, readBody, SCRIPT_CONFIRM_HEADER, redactTaskSecrets, restoreTaskSecrets } from '../http-utils.js';
+import {
+  validateTaskType,
+  RESERVED_TASK_IDS,
+  isCodeExecutingTask,
+} from '../task-transfer.js';
+import { sanitizeAdaptiveConfig } from '../adaptive.js';
+import { sanitizeValidators } from '../validators.js';
+
+export const NOT_FOUND = { ok: false, error: 'Task not found' };
+export const NOT_ALLOWED = { ok: false, error: 'Method not allowed' };
+
+/**
+ * A task declared in the profile config is owned by that file (#50): the next
+ * plugin start would revert any change made here, so every mutating route
+ * refuses it and says where the task really lives.
+ */
+export function refuseConfigOwned(res, id) {
+  sendJson(res, 409, { ok: false, error: configOwnedMessage(id) });
+}
+
+// ------------------------------------------------------------- collection
+
+export async function handleTaskCollection({ store, scheduler, collection, req, res, url, scope, apiToken, ctx }) {
+  // The alias family only exists for individual tasks.
+  if (scope === 'action' || !collection) {
+    sendJson(res, 405, NOT_ALLOWED);
+    return;
+  }
+  if (req.method === 'GET') {
+    if (rejectCrossOrigin(req, res, { apiToken, ctx })) return;
+    listTasks({ store, scheduler, collection, req, res, url });
+    return;
+  }
+  if (req.method === 'POST') {
+    await createOrUpdateTask({ store, scheduler, req, res, apiToken, ctx: undefined });
+    return;
+  }
+  sendJson(res, 405, NOT_ALLOWED);
+}
+
+export function listTasks({ store, scheduler, collection, req, res, url }) {
+  const status = url.searchParams.get('status') || 'all';
+  const query = url.searchParams.get('query') || '';
+  const list = store.list({ status, query }).map((t) => ({
+    ...redactTaskSecrets(t),
+    running: scheduler.isRunning(t.id),
+    runningSince: scheduler.runningSince(t.id),
+  }));
+  const stats = store.getAggregatedStats();
+  const payload = { ok: true, tasks: list, recommendations: collection.recommendations, stats };
+
+  // Calculate ETag based on payload JSON representation (#134)
+  const bodyString = JSON.stringify(payload);
+  const etag = 'W/"' + createHash('sha1').update(bodyString).digest('hex') + '"';
+
+  if (req && req.headers) {
+    const ifNoneMatch = req.headers['if-none-match'];
+    if (ifNoneMatch && (ifNoneMatch === etag || ifNoneMatch === etag.slice(2))) {
+      res.writeHead(304, { 'ETag': etag, 'Cache-Control': 'no-cache' });
+      res.end();
+      return;
+    }
+  }
+
+  if (typeof res.setHeader === 'function') {
+    res.setHeader('ETag', etag);
+    res.setHeader('Cache-Control', 'no-cache');
+  }
+  sendJson(res, 200, payload);
+}
+
+export async function createOrUpdateTask({ store, scheduler, req, res, apiToken, ctx }) {
+  if (rejectCrossOrigin(req, res, { apiToken, ctx })) return;
+  const { body: rawBody, error } = await readBody(req, res);
+  if (error) return;
+  const existing = rawBody.id ? store.get(rawBody.id) : null;
+  const body = existing ? restoreTaskSecrets(rawBody, existing) : rawBody;
+  if (!body.title || !body.schedule || !body.prompt) {
+    sendJson(res, 400, { ok: false, error: 'Fields title, schedule and prompt are required' });
+    return;
+  }
+  const unknownChannels = unknownChannelIds(body.channels);
+  if (unknownChannels.length) {
+    sendJson(res, 400, {
+      ok: false,
+      error: 'Unknown channel ids: ' + unknownChannels.join(', '),
+      unknownChannels,
+    });
+    return;
+  }
+  const taskType = normalizeTaskType(body.type);
+  if ((CODE_EXECUTING_TYPES.includes(taskType) || isCodeExecutingTask(body)) && req.headers[SCRIPT_CONFIRM_HEADER] !== 'script') {
+    sendJson(res, 403, { ok: false, error: `Creating code-executing 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;
+  }
+  let parsed;
+  try {
+    parsed = parseScheduleExpression(body.schedule);
+  } catch (err) {
+    sendJson(res, 400, { ok: false, error: err.message });
+    return;
+  }
+  // A client-supplied id must not shadow the collection routes under
+  // /dsh-cron/tasks, otherwise that task could never be fetched or deleted
+  // again (#42 review finding).
+  if (body.id && RESERVED_TASK_IDS.includes(String(body.id))) {
+    sendJson(res, 400, { ok: false, error: `Task id "${body.id}" is reserved` });
+    return;
+  }
+  // Create-or-update with an existing id is an update too, so the config-owned
+  // refusal must apply here as well — otherwise the POST route would be a way
+  // around the guard on PATCH (#50 review finding).
+  if (body.id) {
+    const existing = store.get(body.id);
+    if (existing && existing.managedBy === MANAGED_BY_CONFIG) {
+      refuseConfigOwned(res, body.id);
+      return;
+    }
+  }
+  let task;
+  try {
+    task = store.set(buildTaskRecord(store, body, taskType, parsed));
+  } catch (err) {
+    sendJson(res, 500, { ok: false, error: 'Failed to persist task: ' + err.message });
+    return;
+  }
+  if (task.status === 'active') {
+    scheduler.scheduleTask(task);
+  } else {
+    scheduler.pauseTask(task.id);
+  }
+  sendJson(res, 200, { ok: true, task: redactTaskSecrets(task) });
+}
+
+/** Merge a create/update payload onto the stored task, if any. */
+export function buildTaskRecord(store, body, taskType, parsed) {
+  const current = body.id ? store.get(body.id) : null;
+  const resolvedStatus = body.status || (current ? current.status : 'active');
+  return {
+    id: body.id,
+    title: body.title,
+    schedule: parsed.cronPattern || body.schedule,
+    scheduleText: body.scheduleText || parsed.humanText,
+    prompt: body.prompt,
+    type: taskType,
+    delivery: body.delivery || 'current',
+    status: resolvedStatus,
+    provider: body.provider || undefined,
+    model: body.model || undefined,
+    fallbackProvider: body.fallbackProvider || undefined,
+    fallbackModel: body.fallbackModel || undefined,
+    notifyTelegram: body.notifyTelegram !== undefined ? Boolean(body.notifyTelegram) : (current ? current.notifyTelegram : undefined),
+    onlyOnFailure: body.onlyOnFailure !== undefined ? Boolean(body.onlyOnFailure) : (current ? current.onlyOnFailure : undefined),
+    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: !EXTERNAL_RUNTIMES.includes(taskType) && ['default', 'read-only', 'workspace-write', 'danger-full-access', 'full'].includes(body.permissionPreset) ? body.permissionPreset : (current && !EXTERNAL_RUNTIMES.includes(taskType) ? (current.permissionPreset || 'default') : 'default'),
+    validators: Array.isArray(body.validators) ? sanitizeValidators(body.validators) : (current ? current.validators : undefined),
+    ...mergeExecutionFields(current, body, parsed),
+  };
+}
+
+// export/import logic moved to ./api-import-export.js
+
+/**
+ * Runtime and execution settings of a task, merged onto the stored one. Split
+ * out of buildTaskRecord so both stay readable.
+ */
+export function mergeExecutionFields(current, body, parsed) {
+  return {
+    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 : ''),
+    silentRule: body.silentRule !== undefined ? String(body.silentRule) : (current ? current.silentRule : ''),
+    inspectOnFailure: body.inspectOnFailure !== undefined ? Boolean(body.inspectOnFailure) : (current ? Boolean(current.inspectOnFailure) : false),
+    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),
+    captureGitDiff: body.captureGitDiff !== undefined ? Boolean(body.captureGitDiff) : (body.captureDiff !== undefined ? Boolean(body.captureDiff) : (current ? current.captureGitDiff : undefined)),
+    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 && parsed.isOneShot) || (body && body.oneShot)),
+    targetTimestamp: parsed && parsed.isOneShot
+      ? (current && current.schedule === (parsed.cronPattern || body.schedule) ? (current.targetTimestamp || parsed.targetTimestamp) : parsed.targetTimestamp)
+      : (current ? current.targetTimestamp : undefined),
+    costLimitUsd: body.costLimitUsd !== undefined ? (body.costLimitUsd === null ? null : (Number(body.costLimitUsd) > 0 ? Number(body.costLimitUsd) : null)) : (current ? current.costLimitUsd : undefined),
+    dailyCostLimitUsd: body.dailyCostLimitUsd !== undefined ? (body.dailyCostLimitUsd === null ? null : (Number(body.dailyCostLimitUsd) > 0 ? Number(body.dailyCostLimitUsd) : null)) : (current ? current.dailyCostLimitUsd : undefined),
+    tokenLimit: body.tokenLimit !== undefined ? (body.tokenLimit === null ? null : (Number(body.tokenLimit) > 0 ? Number(body.tokenLimit) : null)) : (current ? current.tokenLimit : undefined),
+    pausedReason: body.pausedReason !== undefined ? (body.pausedReason ? String(body.pausedReason) : null) : (current ? current.pausedReason : undefined),
+    agentPreset: body.agentPreset !== undefined ? String(body.agentPreset).trim() : (current ? (current.agentPreset || '') : ''),
+    targetSessionId: body.targetSessionId !== undefined ? String(body.targetSessionId).trim() : (current ? (current.targetSessionId || '') : ''),
+    targetSessionReset: body.targetSessionReset !== undefined ? String(body.targetSessionReset).trim() : (current ? (current.targetSessionReset || 'never') : 'never'),
+    sessionTitle: body.sessionTitle !== undefined ? String(body.sessionTitle).trim() : (current ? (current.sessionTitle || '') : ''),
+    webhookEnabled: body.webhookEnabled !== undefined
+      ? Boolean(body.webhookEnabled)
+      : (body.webhookTrigger?.enabled !== undefined ? Boolean(body.webhookTrigger.enabled) : (current ? Boolean(current.webhookEnabled || current.webhookTrigger?.enabled) : false)),
+    webhookToken: body.webhookToken !== undefined
+      ? String(body.webhookToken).trim()
+      : (body.webhookTrigger?.token ? String(body.webhookTrigger.token).trim() : (current ? (current.webhookToken || current.webhookTrigger?.token || '') : '')),
+    webhookSecret: body.webhookSecret !== undefined
+      ? String(body.webhookSecret).trim()
+      : (body.webhookTrigger?.secret ? String(body.webhookTrigger.secret).trim() : (current ? (current.webhookSecret || current.webhookTrigger?.secret || '') : '')),
+    webhookDebounceMs: body.webhookDebounceMs !== undefined
+      ? (Number(body.webhookDebounceMs) || 0)
+      : (body.webhookTrigger?.debounceMs !== undefined ? (Number(body.webhookTrigger.debounceMs) || 0) : (current ? (Number(current.webhookDebounceMs || current.webhookTrigger?.debounceMs) || 0) : 0)),
+    onSuccess: body.onSuccess !== undefined ? String(body.onSuccess).trim() : (current ? (current.onSuccess || '') : ''),
+    onFailure: body.onFailure !== undefined ? String(body.onFailure).trim() : (current ? (current.onFailure || '') : ''),
+    heartbeatIntervalSeconds: body.heartbeatIntervalSeconds !== undefined ? Number(body.heartbeatIntervalSeconds) : (current ? (Number(current.heartbeatIntervalSeconds) || 0) : 0),
+    gracePeriodSeconds: body.gracePeriodSeconds !== undefined ? Number(body.gracePeriodSeconds) : (current ? (Number(current.gracePeriodSeconds) || 300) : 300),
+    preflightType: body.preflightType !== undefined ? String(body.preflightType).trim().toLowerCase() : (current ? (current.preflightType || 'none') : 'none'),
+    preflightTarget: body.preflightTarget !== undefined ? String(body.preflightTarget).trim() : (current ? (current.preflightTarget || '') : ''),
+    priority: body.priority !== undefined ? (Number(body.priority) || 5) : (current ? (Number(current.priority) || 5) : 5),
+    concurrencyGroup: body.concurrencyGroup !== undefined ? String(body.concurrencyGroup).trim() : (current ? (current.concurrencyGroup || 'default') : 'default'),
+    selfHealingCommand: body.selfHealingCommand !== undefined ? String(body.selfHealingCommand).trim() : (current ? (current.selfHealingCommand || '') : ''),
+    autoDiagnose: body.autoDiagnose !== undefined ? Boolean(body.autoDiagnose) : (current ? Boolean(current.autoDiagnose) : false),
+    adaptive: body.adaptive !== undefined ? sanitizeAdaptiveConfig(body.adaptive) : (current ? current.adaptive : undefined),
+    adaptiveState: current ? current.adaptiveState : undefined,
+  };
+}
+
+

package/lib/routes/api-helpers.js

@@ -0,0 +1,100 @@
+import { calculate24hTimeline } from '../timeline.js';
+import { previewSchedule } from '../scheduler.js';
+import { sendJson, readBody, rejectCrossOrigin } from '../http-utils.js';
+
+const NOT_ALLOWED = { ok: false, error: 'Method not allowed' };
+
+export function handleHeartbeatPing({ store, req, res, taskId, apiToken: explicitToken, ctx }) {
+  if (req.method !== 'POST') {
+    sendJson(res, 405, NOT_ALLOWED);
+    return;
+  }
+  const apiToken = explicitToken || store?.getSettings?.()?.apiToken;
+  if (rejectCrossOrigin(req, res, { apiToken, ctx })) return;
+
+  const task = store.get(taskId);
+  if (!task) {
+    sendJson(res, 404, { ok: false, error: 'Task not found' });
+    return;
+  }
+  const result = typeof store.recordHeartbeat === 'function' ? store.recordHeartbeat(taskId) : null;
+  if (!result) {
+    sendJson(res, 500, { ok: false, error: 'Could not record heartbeat' });
+    return;
+  }
+  sendJson(res, 200, result);
+}
+
+export async function handleSchedulePreview({ req, res, url, store, apiToken: explicitToken, ctx }) {
+  const apiToken = explicitToken || store?.getSettings?.()?.apiToken;
+  if (rejectCrossOrigin(req, res, { apiToken, ctx })) return;
+
+  let schedule = '';
+  let timezone = '';
+  let count = 5;
+
+  if (req.method === 'POST') {
+    const { body, error } = await readBody(req, res);
+    if (error) return;
+    schedule = body.schedule || '';
+    timezone = body.timezone || '';
+    count = body.count || 5;
+  } else if (req.method === 'GET') {
+    schedule = url.searchParams.get('schedule') || '';
+    timezone = url.searchParams.get('timezone') || '';
+    count = parseInt(url.searchParams.get('count') || '5', 10);
+  } else {
+    sendJson(res, 405, NOT_ALLOWED);
+    return;
+  }
+
+  if (!schedule) {
+    sendJson(res, 400, { ok: false, error: 'Field "schedule" is required' });
+    return;
+  }
+
+  try {
+    const preview = previewSchedule(schedule, { timezone, count });
+    sendJson(res, 200, { ok: true, ...preview });
+  } catch (err) {
+    sendJson(res, 400, { ok: false, error: err.message });
+  }
+}
+
+export async function handleDryRunTask({ store, scheduler, req, res, id, apiToken: explicitToken, ctx }) {
+  const apiToken = explicitToken || store?.getSettings?.()?.apiToken;
+  if (rejectCrossOrigin(req, res, { apiToken, ctx })) return;
+  const task = store.get(id);
+  if (!task) {
+    sendJson(res, 404, { ok: false, error: 'Task not found' });
+    return;
+  }
+
+  try {
+    const outcome = await scheduler.runTask(id, { dryRun: true });
+    sendJson(res, 200, outcome || { ok: true, status: 'completed' });
+  } catch (err) {
+    sendJson(res, 500, { ok: false, error: err.message });
+  }
+}
+
+export async function handleScheduleTimeline({ req, res, url, store, scheduler, apiToken: explicitToken, ctx }) {
+  const apiToken = explicitToken || store?.getSettings?.()?.apiToken;
+  if (rejectCrossOrigin(req, res, { apiToken, ctx })) return;
+
+  if (req.method !== 'GET') {
+    sendJson(res, 405, NOT_ALLOWED);
+    return;
+  }
+
+  const hours = parseInt(url.searchParams.get('hours') || '24', 10);
+  const tasks = typeof store?.list === 'function' ? store.list() : [];
+  const maxConcurrent = store?.getSettings?.()?.maxConcurrent || 3;
+
+  try {
+    const timeline = calculate24hTimeline({ tasks, maxConcurrent, hoursCount: hours });
+    sendJson(res, 200, { ok: true, timeline });
+  } catch (err) {
+    sendJson(res, 500, { ok: false, error: err.message });
+  }
+}

package/lib/routes/api-import-export.js

@@ -0,0 +1,155 @@
+import { logger } from '../logger.js';
+import { randomUUID } from 'node:crypto';
+import {
+  buildTaskExport,
+  validateImportDocument,
+  planImport,
+  hasCodeExecutingTask,
+  IMPORT_STRATEGIES,
+} from '../task-transfer.js';
+import { unknownChannelIds } from '../channels.js';
+import {
+  sendJson,
+  readBody,
+  SCRIPT_CONFIRM_HEADER,
+} from '../http-utils.js';
+import { MANAGED_BY_CONFIG } from '../config-jobs.js';
+
+export function handleTaskExport({ store, req, res }) {
+  let sanitize = false;
+  if (req && req.url) {
+    try {
+      const parsed = new URL(req.url, 'http://127.0.0.1');
+      sanitize = parsed.searchParams.get('sanitize') === 'true' || parsed.searchParams.get('redact') === 'true';
+    } catch (urlErr) {
+      logger.debug('[dsh-cron] export url parse fallback:', urlErr.message);
+    }
+  }
+  const doc = buildTaskExport(store.list({ status: 'all' }), { sanitize });
+  sendJson(res, 200, { ok: true, document: doc, count: doc.tasks.length, sanitized: sanitize });
+}
+
+export async function handleTaskImport({ store, scheduler, req, res }) {
+  const { body, error } = await readBody(req, res);
+  if (error) return;
+  const strategy = IMPORT_STRATEGIES.includes(body && body.strategy) ? body.strategy : 'skip';
+  const checked = validateImportDocument(body && body.document);
+  if (!checked.ok) {
+    sendJson(res, 400, { ok: false, error: checked.error });
+    return;
+  }
+  // The import file is external input: importing code-executing tasks needs
+  // the same explicit confirmation that creating one over HTTP needs,
+  // otherwise a hand-edited file would bypass that gate (#86).
+  if (hasCodeExecutingTask(checked.tasks) && req.headers[SCRIPT_CONFIRM_HEADER] !== 'script') {
+    sendJson(res, 403, {
+      ok: false,
+      error: `Importing code-executing tasks over HTTP requires the ${SCRIPT_CONFIRM_HEADER}: script header`,
+    });
+    return;
+  }
+  // #121: an imported file may name a channel this build no longer has. The
+  // import stays tolerant by design (#42), but the loss is reported instead of
+  // being invisible.
+  const rawTasks = Array.isArray(body.document && body.document.tasks) ? body.document.tasks : [];
+  const droppedChannels = [];
+  for (const item of rawTasks) {
+    for (const id of unknownChannelIds(item.channels)) {
+      if (!droppedChannels.includes(id)) droppedChannels.push(id);
+    }
+  }
+  if (droppedChannels.length) {
+    logger.warn('[dsh-cron] import: unknown channel ids were dropped: ' + droppedChannels.join(', '));
+  }
+  const existingIds = store.list({ status: 'all' }).map((x) => x.id);
+  const plan = planImport(checked.tasks, existingIds, strategy);
+  // Replacing a task the config owns would be undone at the next start, and
+  // the id could then hold two different tasks (#50).
+  const configConflicts = plan.replace
+    .map((item) => item.id)
+    .filter((taskId) => {
+      const stored = store.get(taskId);
+      return stored && stored.managedBy === MANAGED_BY_CONFIG;
+    });
+  if (configConflicts.length) {
+    sendJson(res, 409, {
+      ok: false,
+      error: 'These tasks are declared in the profile config and cannot be replaced by an import: ' + configConflicts.join(', '),
+    });
+    return;
+  }
+  const summary = { add: plan.add.length, replace: plan.replace.length, skip: plan.skip.length };
+  if (body && body.dryRun) {
+    sendJson(res, 200, {
+      ok: true,
+      dryRun: true,
+      strategy: plan.strategy,
+      summary,
+      codeExecuting: hasCodeExecutingTask(plan.add.concat(plan.replace)),
+      unknownChannels: droppedChannels,
+    });
+    return;
+  }
+  const applied = applyImportPlan({ store, scheduler, plan });
+  if (applied.error) {
+    sendJson(res, 500, { ok: false, error: applied.error });
+    return;
+  }
+  sendJson(res, 200, {
+    ok: true,
+    imported: applied.imported.length,
+    summary,
+    unknownChannels: droppedChannels,
+    tasks: applied.imported,
+  });
+}
+
+/**
+ * Write an import plan. Every imported task is paused (the file's status is
+ * ignored) and every touched id is disarmed explicitly, because writing
+ * "paused" does not stop an already-armed croner job. A failed write rolls the
+ * store back so a partial import cannot survive.
+ */
+export function applyImportPlan({ store, scheduler, plan }) {
+  const imported = [];
+  const rollback = [];
+  const disarm = [];
+  try {
+    for (const task of plan.add) {
+      const before = store.get(task.id);
+      const created = store.set({ ...task, id: task.id || randomUUID(), status: 'paused', updatedAt: Date.now() });
+      imported.push(created);
+      rollback.push({ id: created.id, previous: before || null });
+      disarm.push(created.id);
+    }
+    for (const task of plan.replace) {
+      const before = store.get(task.id);
+      if (!before) continue;
+      const replaced = store.set({ ...task, id: task.id, status: 'paused', updatedAt: Date.now() });
+      imported.push(replaced);
+      rollback.push({ id: replaced.id, previous: before });
+      disarm.push(replaced.id);
+    }
+  } catch (writeErr) {
+    for (const entry of rollback.reverse()) {
+      try {
+        if (entry.previous) store.set(entry.previous);
+        else store.delete(entry.id);
+      } catch (rollbackErr) {
+        logger.warn(`[dsh-cron] import rollback failed for task "${entry.id}":`, rollbackErr?.message || rollbackErr);
+      }
+    }
+    return { imported: [], error: `Import failed and was rolled back: ${writeErr.message}` };
+  }
+  // Disarm outside the write transaction: pauseTask is idempotent and a
+  // failure here must not undo a successful import.
+  for (const id of disarm) {
+    try {
+      scheduler.pauseTask(id);
+    } catch (err) {
+      logger.error('[dsh-cron] import: could not pause task', id + ':', err.message);
+    }
+  }
+  return { imported };
+}
+