@goodandready/dsh-cron 0.2.37 → 0.2.39

package/README.md

@@ -452,6 +452,7 @@ Developer-facing, no behaviour change. `parseScheduleExpression` was split into
 - **Modular Client Architecture (#150)**: Decomposed monolithic `lib/client.js` (~3950 lines) into 14 focused, single-responsibility fragments under `lib/client-src/` (none exceeding 580 lines). Integrated zero-dependency build script `scripts/build-client.mjs` wired into `package.json` (`build:client`, `pretest`). Development fragments are excluded from npm distribution via `"files": ["lib/*.js", ...]`.
 - **DSH Theme Tokens & Visual Standardization (#149)**: Replaced inline styles on task type badges (`onSuccess`, `onFailure`, `heartbeat`, `targetSession`, `preflight`) with dedicated `.dsh-cron-tag-*` CSS classes powered by semantic `--dsh-cron-*` theme variables. Modal overlay now adapts dynamically using `var(--dsw-alias-bg-mask, rgba(0, 0, 0, 0.75))`, and keyframe pulse animations use theme variables without hardcoded RGBA.
 - **Label Governance & Triage Audit (#95)**: Standardized 100% of repository issues and triage on the canonical repo-level label set.
+- **Style Self-Healing on Dynamic DOM Sweeps (#263 / GH-4)**: Watches `<head>` and `<html>` via `MutationObserver` alongside a 2s backstop interval and `visibilitychange` listener (`startStyleSelfHeal`), automatically re-attaching or repairing the `<style id="dsh-cron-styles">` tag if swept by host head re-renders, theme switches, or neighbor cleanups.
 
 ---
 
@@ -487,7 +488,7 @@ dsh-cron:
   onlyOnFailure: false         # deliver reports only for failed runs
   kanbanBaseUrl: "http://127.0.0.1:3000"  # dsh-kanban HTTP API base URL
   defaultTimezone: ""          # default IANA time zone for schedules (empty = server local)
-  maxConcurrent: 0             # max parallel task runs (0 = unlimited)
+  maxConcurrent: 2             # max parallel task runs (default 2, 0 = unlimited)
   heartbeatUrl: ""             # dead man's snitch URL pinged on the heartbeat interval
   heartbeatIntervalSec: 0      # heartbeat ping interval in seconds (0 = off)
   # --- delivery channels ---
@@ -512,7 +513,15 @@ dsh-cron:
   apiToken: ""                 # bearer token for the external /dsh-cron/api/* surface (masked; empty = 503)
 ```
 
-### Configuration Parameters
+#### Timers, Intervals & Concurrency Groups Hardening (0.2.39)
+
+- **32-Bit Timer Overflow Protection**: One-shot tasks scheduled >24.85 days in the future (exceeding Node's 32-bit signed integer `setTimeout` limit of 2,147,483,647 ms) are safely executed via bounded timer chunking, preventing immediate misfires.
+- **Persistent Relative One-Shot Deadlines**: Relative one-shot tasks (`in 30m`, `in 2h`) maintain their absolute target timestamp across daemon restarts, store reloads, pause/resume, and metadata edits. Deadlines are only recalculated upon explicit schedule modifications.
+- **Strict Interval Validation & Normalization**: Unsupported irregular intervals exceeding 59 minutes (e.g. `every 90m`) are validated and rejected upfront with HTTP 400 before persisting. Clean hourly multiples (e.g. `every 120m` -> `every 2h`, `every 24h` -> `every 1d`) are automatically converted to valid cron patterns.
+- **Unified Safe Concurrency Defaults**: The Config schema and TaskScheduler now uniformly default `maxConcurrent` to safe cap `2` (0 explicitly denotes unlimited).
+- **Concurrency Group Pool Isolation**: Tasks configured with `concurrencyGroup` have per-group execution limits enforced during admission and queue draining (default 1 concurrent run per named group). Tasks in separate groups run concurrently up to `maxConcurrent`, while queued tasks drain as soon as group capacity becomes available.
+
+## Configuration Parameters
 
 | Parameter | Type | Default | Description |
 |:---|:---|:---|:---|
@@ -522,7 +531,7 @@ dsh-cron:
 | `onlyOnFailure` | `boolean` | `false` | Global switch: deliver reports only for `error`/`timeout` runs |
 | `kanbanBaseUrl` | `string` | `"http://127.0.0.1:3000"` | Base URL of the `dsh-kanban` HTTP API used for automatic card creation |
 | `defaultTimezone` | `string` | `""` | Default IANA time zone for task schedules; empty = server local time |
-| `maxConcurrent` | `number` | `0` | Cap on parallel task runs; extra runs are recorded as `skipped` (0 = unlimited) |
+| `maxConcurrent` | `number` | `2` | Cap on parallel task runs; extra runs are recorded as `skipped` (default 2, 0 = unlimited) |
 | `heartbeatUrl` | `string` | `""` | Dead man's snitch URL pinged every `heartbeatIntervalSec` while the scheduler is alive |
 | `heartbeatIntervalSec` | `number` | `0` | Heartbeat ping interval in seconds (0 = disabled) |
 | `botTokenRef` | `string` | `""` | Name of the DSH credential holding the Telegram bot token; resolved at send time (falls back to `botToken`, then the messenger-gateway settings, then the `CRON_TELEGRAM_BOT_TOKEN` environment variable) |

package/README.ru.md

@@ -319,6 +319,7 @@ cron({
 - **Модульная архитектура клиентской части (#150)**: Монолитный файл `lib/client.js` (~3950 строк) декомпозирован на 14 независимых специализированных модулей в каталоге `lib/client-src/` (каждый строго <= 580 строк). Сборка `lib/client.js` выполняется легковесным скриптом `scripts/build-client.mjs` перед запуском тестов и сборки. Исходные фрагменты исключены из npm-дистрибутива через `"files": ["lib/*.js", ...]`.
 - **Семантические токены тем DSH (#149)**: Инлайн-стили тегов типа задач (`onSuccess`, `onFailure`, `heartbeat`, `targetSession`, `preflight`) переведены на выделенные CSS-классы `.dsh-cron-tag-*` на базе переменных темы `--dsh-cron-*`. Оверлей модальных окон переведен на адаптивную маску `var(--dsw-alias-bg-mask, rgba(0, 0, 0, 0.75))`, а анимация пульсации избавлена от захардкоженных значений RGBA.
 - **Аудит меток репозитория (#95)**: Подтверждена 100% консистентность использования канонического репозиторного набора меток и фильтрации задач.
+- **Самовосстановление стилей при динамических перерисовках DOM (#263 / GH-4)**: Отслеживает `<head>` и `<html>` через `MutationObserver`, резервный интервал 2с и событие `visibilitychange` (`startStyleSelfHeal`), мгновенно восстанавливая узел `<style id="dsh-cron-styles">` при перерисовке заголовка хостом, смене темы или очистке соседними модулями.
 
 ---
 
@@ -352,7 +353,7 @@ dsh-cron:
   onlyOnFailure: false         # отправлять отчёты только при сбоях
   kanbanBaseUrl: "http://127.0.0.1:3000"  # базовый URL HTTP API dsh-kanban
   defaultTimezone: ""          # IANA-зона по умолчанию (пусто = серверное время)
-  maxConcurrent: 0             # максимум параллельных запусков (0 = без лимита)
+  maxConcurrent: 2             # максимум параллельных запусков (по умолчанию 2, 0 = без лимита)
   heartbeatUrl: ""             # URL dead man's snitch, пингуется по интервалу
   heartbeatIntervalSec: 0      # интервал heartbeat-пинга в секундах (0 = выключено)
   # --- каналы доставки ---
@@ -512,7 +513,7 @@ bash deploy.sh verify [exact-version]
 | `onlyOnFailure` | `boolean` | `false` | Глобальный режим «только при сбоях» (`error`/`timeout`) |
 | `kanbanBaseUrl` | `string` | `"http://127.0.0.1:3000"` | Базовый URL HTTP API `dsh-kanban` для автоматических карточек |
 | `defaultTimezone` | `string` | `""` | IANA-зона по умолчанию для расписаний; пусто = серверное время |
-| `maxConcurrent` | `number` | `0` | Лимит параллельных запусков; лишние помечаются `skipped` (0 = без лимита) |
+| `maxConcurrent` | `number` | `2` | Лимит параллельных запусков; лишние помечаются `skipped` (по умолчанию 2, 0 = без лимита) |
 | `heartbeatUrl` | `string` | `""` | URL dead man's snitch, пингуемый каждый `heartbeatIntervalSec`, пока жив планировщик |
 | `heartbeatIntervalSec` | `number` | `0` | Интервал heartbeat-пинга в секундах (0 = выключено) |
 | `botTokenRef` | `string` | `""` | Имя credential DSH с токеном Telegram-бота; резолвится при отправке (фолбэк: `botToken` → настройки messenger-gateway → переменная окружения `CRON_TELEGRAM_BOT_TOKEN`) |
@@ -590,3 +591,12 @@ node scripts/ci-preflight.mjs
 ## 📄 Лицензия
 
 MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)
+
+### Надёжность таймеров, интервалов и групп параллелизма (0.2.39)
+
+- **Защита от 32-битного переполнения таймера**: Одноразовые задачи, запланированные более чем на 24.85 дня вперёд (превышающие лимит 32-битного целого `setTimeout` в 2 147 483 647 мс в Node.js), выполняются через порционный таймер и не запускаются раньше времени.
+- **Сохранение первоначального дедлайна относительных задач**: Задачи вида `in 30m` или `через 2 часа` сохраняют первоначальный целевой таймстемп при перезапусках сервера, перезагрузке хранилища, паузе/возобновлении и изменении полей задачи (title, tags, channels). Новый дедлайн вычисляется только при явном изменении поля расписания.
+- **Строгая валидация и нормализация интервалов**: Недопустимые минутные интервалы свыше 59 минут (например, `every 90m`) отклоняются на входе с кодом HTTP 400 без создания неработающей активной задачи. Кратные интервалы (например, `every 120m` -> `every 2h`, `every 24h` -> `every 1d`) корректно приводятся к валидным cron-паттернам.
+- **Единый безопасный лимит maxConcurrent**: Схема Config и планировщик TaskScheduler теперь согласованно используют лимит по умолчанию `2` (0 остаётся явным выбором безлимитного режима).
+- **Изоляция пулов через concurrencyGroup**: Поле `concurrencyGroup` теперь строго контролируется при допуске задач и опустошении очереди (по умолчанию 1 параллельный запуск на именованную группу). Задачи из разных групп исполняются параллельно в пределах общего `maxConcurrent`, а задачи с политикой `queue` стартуют сразу при освобождении слота своей группы.
+

package/README.zh.md

@@ -444,6 +444,7 @@ bash deploy.sh verify [exact-version]
 - **客户端模块化架构 (#150)**: 将庞大的单文件 `lib/client.js` (约 3950 行) 拆分为 `lib/client-src/` 下的 14 个高内聚模块文件 (各模块严格 <= 580 行)。集成零依赖构建脚本 `scripts/build-client.mjs` 并接入 `package.json` (`build:client`, `pretest`)，通过 `"files": ["lib/*.js", ...]` 避免开发源码冗余打包进 npm 发布包。
 - **DSH 语义化主题变量对齐 (#149)**: 将任务类型标签 (`onSuccess`, `onFailure`, `heartbeat`, `targetSession`, `preflight`) 的内联样式全部替换为基于主题变量的 `.dsh-cron-tag-*` 类；模态框遮罩层接入自适应主题遮罩变量 `var(--dsw-alias-bg-mask, rgba(0, 0, 0, 0.75))`，移除脉冲动画关键帧中的硬编码 RGBA。
 - **标签治理与工单审计 (#95)**: 审计并确认全仓库 100% 统一规范使用仓库级标签集。
+- **动态 DOM 清理下的样式自动恢复（#263 / GH-4）**: 通过 `MutationObserver`、2 秒兜底定时器与 `visibilitychange` 事件（`startStyleSelfHeal`）监听 `<head>` 与 `<html>`，当宿主重绘 `<head>`、切换主题或邻近插件清理样式时，自动重新注入并修复 `<style id="dsh-cron-styles">` 标签。
 
 ---
 
@@ -477,7 +478,7 @@ dsh-cron:
   onlyOnFailure: false         # 仅失败时投递报告
   kanbanBaseUrl: "http://127.0.0.1:3000"  # dsh-kanban HTTP API 基础地址
   defaultTimezone: ""          # 默认 IANA 时区（空 = 服务器本地）
-  maxConcurrent: 0             # 最大并行运行数（0 = 不限）
+  maxConcurrent: 2             # 最大并行运行数（默认 2，0 = 不限）
   heartbeatUrl: ""             # 心跳上报 URL（dead man's snitch）
   heartbeatIntervalSec: 0      # 心跳间隔秒数（0 = 关闭）
   # --- 投递渠道 ---
@@ -512,7 +513,7 @@ dsh-cron:
 | `onlyOnFailure` | `boolean` | `false` | 全局开关：仅对 `error`/`timeout` 运行投递报告 |
 | `kanbanBaseUrl` | `string` | `"http://127.0.0.1:3000"` | 用于自动卡片的 `dsh-kanban` HTTP API 基础地址 |
 | `defaultTimezone` | `string` | `""` | 任务调度的默认 IANA 时区；空 = 服务器本地时间 |
-| `maxConcurrent` | `number` | `0` | 并行运行上限；超出的运行记录为 `skipped`（0 = 不限） |
+| `maxConcurrent` | `number` | `2` | 并行运行上限；超出的运行记录为 `skipped`（默认 2，0 = 不限） |
 | `heartbeatUrl` | `string` | `""` | 心跳上报 URL，调度器存活期间按 `heartbeatIntervalSec` 间隔 GET |
 | `heartbeatIntervalSec` | `number` | `0` | 心跳间隔秒数（0 = 关闭） |
 | `botTokenRef` | `string` | `""` | 保存 Telegram bot token 的 DSH 凭据名称；发送时解析（回退顺序：`botToken` → messenger-gateway 设置 → 环境变量 `CRON_TELEGRAM_BOT_TOKEN`） |
@@ -590,3 +591,12 @@ node scripts/ci-preflight.mjs
 ## 📄 许可证
 
 MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)
+
+### 定时器、间隔与并发分组精度强化 (0.2.39)
+
+- **32位定时器溢出防护**：计划在 24.85 天以后的单次任务（超出 Node.js `setTimeout` 32位有符号整数上限 2,147,483,647 毫秒）通过分段定时器安全挂起，杜绝立即误触发。
+- **相对单次任务持久截止时间**：相对单次任务（如 `in 30m`、`in 2h`）在服务重启、存储重载、暂停/恢复以及修改元数据时完整保留初始目标绝对时间戳，仅在显式修改调度表达式时重新计算。
+- **严格的时间间隔校验与转换**：对于无法用标准 Cron 分钟步进表示的超限分钟间隔（如 `every 90m`），在持久化前返回 HTTP 400 拦截；规整整倍数（如 `every 120m` -> `every 2h`、`every 24h` -> `every 1d`）自动转为合法 Cron 表达式。
+- **统一安全并发默认值**：配置规范（Config）与调度器（TaskScheduler）全面对齐默认并发上限 `maxConcurrent = 2`（0 仅作为显式无限制选项）。
+- **并发分组隔离调度**：任务的 `concurrencyGroup` 属性全面接入调度仲裁与队列排队（同名分组默认限流 1 个并发执行），不同分组可并发运行直至 `maxConcurrent`，队列任务随所属分组资源释放立即触发。
+

package/lib/api.js

@@ -200,7 +200,13 @@ async function createOrUpdateTask({ store, scheduler, req, res, apiToken }) {
     sendJson(res, 400, { ok: false, error: typeError });
     return;
   }
-  const parsed = parseScheduleExpression(body.schedule);
+  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).
@@ -480,6 +486,9 @@ function mergeExecutionFields(current, body, parsed) {
     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),

package/lib/client.js

@@ -847,17 +847,63 @@ window.__ModuleLoader__.load({
       }
     `;
 
+    const STYLE_ID = 'dsh-cron-styles';
+
     function ensureStyles() {
-      if (typeof document === 'undefined') return;
-      let el = document.getElementById('dsh-cron-styles');
-      if (!el) {
+      if (typeof document === 'undefined') return null;
+      let el = document.getElementById(STYLE_ID);
+      if (el === null) {
+        const head = document.head || document.documentElement;
+        if (!head) return null;
         el = document.createElement('style');
-        el.id = 'dsh-cron-styles';
+        el.id = STYLE_ID;
         // Mark ownership before insertion so neighbor cleanups leave it alone (#91)
         el.dataset.dshPlugin = 'dsh-cron';
-        document.head.appendChild(el);
+        el.textContent = STYLES;
+        head.appendChild(el);
+        return el;
       }
-      el.textContent = STYLES;
+      if (el.textContent !== STYLES) el.textContent = STYLES;
+      return el;
+    }
+
+    // Registry is shared across hot reloads so the newest instance owns exactly
+    // one watcher instead of stacking one per module evaluation.
+    const STYLE_HEAL_KEY = '__dshCronStyleHeal';
+    const STYLE_HEAL_INTERVAL_MS = 2000;
+
+    /**
+     * Keep the stylesheet attached: watch <head> (and <html>, which catches a
+     * replaced <head>) and re-attach on demand, with a slow interval as the
+     * backstop. heal() is idempotent and writes nothing while healthy.
+     */
+    function startStyleSelfHeal() {
+      if (typeof document === 'undefined') return () => {};
+      if (typeof window !== 'undefined' && typeof window[STYLE_HEAL_KEY] === 'function') {
+        try { window[STYLE_HEAL_KEY](); } catch (_err) { void _err; }
+      }
+      const heal = () => { try { ensureStyles(); } catch (_err) { void _err; } };
+      heal();
+      let observer = null;
+      try {
+        if (typeof MutationObserver === 'function') {
+          observer = new MutationObserver(heal);
+          if (document.head) observer.observe(document.head, { childList: true });
+          if (document.documentElement) observer.observe(document.documentElement, { childList: true });
+        }
+      } catch (_err) { observer = null; }
+      let timer = null;
+      try { timer = setInterval(heal, STYLE_HEAL_INTERVAL_MS); } catch (_err) { timer = null; }
+      const onVisibility = () => { if (document.visibilityState !== 'hidden') heal(); };
+      try { document.addEventListener('visibilitychange', onVisibility); } catch (_err) { void _err; }
+      const stop = () => {
+        try { if (observer) observer.disconnect(); } catch (_err) { void _err; }
+        try { if (timer !== null) clearInterval(timer); } catch (_err) { void _err; }
+        try { document.removeEventListener('visibilitychange', onVisibility); } catch (_err) { void _err; }
+        if (typeof window !== 'undefined' && window[STYLE_HEAL_KEY] === stop) window[STYLE_HEAL_KEY] = undefined;
+      };
+      if (typeof window !== 'undefined') window[STYLE_HEAL_KEY] = stop;
+      return stop;
     }
 
     function createErrorBoundary() {
@@ -4014,6 +4060,9 @@ window.__ModuleLoader__.load({
 
       const applyActive = () => {
         if (toggle.isOpen()) {
+          // Repair a dropped stylesheet before the panel paints, so opening the
+          // screen never shows an unstyled page (see startStyleSelfHeal).
+          ensureStyles();
           document.documentElement.setAttribute(ACTIVE_ATTR, '');
           document.dispatchEvent(new CustomEvent(ACTIVATE_EVENT, { detail: PANEL }));
         } else {
@@ -4070,7 +4119,7 @@ window.__ModuleLoader__.load({
     }
 
     function apply(ctx) {
-      ensureStyles();
+      const stopStyleSelfHeal = startStyleSelfHeal();
 
       // Register the English canonical strings; rebinding the translator lets
       // the translation plugin drive the active language at runtime (#87).
@@ -4158,7 +4207,7 @@ window.__ModuleLoader__.load({
           mountSidebarJobs(toggle, translate('sidebar.jobsTitle'), (taskId) => { pendingTaskHighlight = taskId; }),
           mountCronScreen(ctx, toggle)
         ];
-        return () => { for (const dispose of off) dispose(); };
+        return () => { for (const dispose of off) dispose(); stopStyleSelfHeal(); };
       }, 'dsh-cron: client overlay');
 
       exports.slots = { card: cardSlot, chip: chipSlot };

package/lib/scheduler-execution.js

@@ -195,6 +195,28 @@ export function beginRun(scheduler, task, taskId, options = {}) {
     return null;
   }
 
+  const group = task.concurrencyGroup && task.concurrencyGroup !== 'default' ? String(task.concurrencyGroup).trim() : null;
+  const groupLimit = scheduler.getGroupLimit ? scheduler.getGroupLimit(group) : (group ? 1 : 0);
+  if (group && groupLimit > 0 && !scheduler.running.has(taskId)) {
+    const runningInGroup = scheduler.getRunningGroupCount ? scheduler.getRunningGroupCount(group) : 0;
+    if (runningInGroup >= groupLimit) {
+      if (task.overlapPolicy === 'queue') {
+        logger.info(`[dsh-cron] Task "${task.title}" (${taskId}) queued by group "${group}" limit (${groupLimit})`);
+        scheduler.queue.push({
+          taskId,
+          options: { ...options },
+          priority: task.priority !== undefined ? task.priority : 5,
+          queuedAt: Date.now(),
+        });
+        scheduler.queue.sort((a, b) => (a.priority - b.priority) || (a.queuedAt - b.queuedAt));
+        return null;
+      }
+      logger.info(`[dsh-cron] Task "${task.title}" (${taskId}) skipped: concurrency group "${group}" limit reached (${groupLimit})`);
+      scheduler.recordSkipped(taskId, `Skipped: concurrency group "${group}" limit reached (${groupLimit} parallel runs)`);
+      return null;
+    }
+  }
+
   const overlapPolicy = task.overlapPolicy || 'skip';
   const active = scheduler.running.get(taskId);
   if (active) {
@@ -225,6 +247,7 @@ export function beginRun(scheduler, task, taskId, options = {}) {
     startedAt: Date.now(),
     queuedRuns: pendingOverlap,
     queueCount: pendingOverlap.length,
+    concurrencyGroup: group || 'default',
   };
   scheduler.running.set(taskId, currentRun);
   return currentRun;
@@ -532,20 +555,41 @@ export async function handleCompleteRun(scheduler, task, taskId, currentRun, out
   const guard = await checkAndApplyBurnGuard(scheduler, taskId, outcome);
   if (guard && guard.exceeded) return;
 
-  while (!scheduler.isStopped && scheduler.queue.length > 0 && scheduler.running.size < scheduler.maxConcurrent) {
-    const nextItem = scheduler.queue.shift();
-    if (!nextItem) break;
-    const queuedTask = scheduler.store.get(nextItem.taskId);
-    if (queuedTask && queuedTask.status === 'active' && !scheduler.isStopped) {
-      setImmediate(() => {
-        if (!scheduler.isStopped) {
-          scheduler.runTask(nextItem.taskId, nextItem.options || {}).catch((runErr) => {
-            bestEffort('drain-queued-task', () => {}, scheduler.logger);
-          });
+  while (!scheduler.isStopped && scheduler.queue.length > 0 && (scheduler.maxConcurrent === 0 || scheduler.running.size < scheduler.maxConcurrent)) {
+    let admittedIndex = -1;
+    for (let i = 0; i < scheduler.queue.length; i++) {
+      const candidate = scheduler.queue[i];
+      const queuedTask = scheduler.store.get(candidate.taskId);
+      if (!queuedTask || queuedTask.status !== 'active') {
+        scheduler.queue.splice(i, 1);
+        i--;
+        continue;
+      }
+      const qGroup = queuedTask.concurrencyGroup && queuedTask.concurrencyGroup !== 'default'
+        ? String(queuedTask.concurrencyGroup).trim()
+        : null;
+      const qLimit = scheduler.getGroupLimit ? scheduler.getGroupLimit(qGroup) : (qGroup ? 1 : 0);
+      if (qGroup && qLimit > 0) {
+        const inGroup = scheduler.getRunningGroupCount ? scheduler.getRunningGroupCount(qGroup) : 0;
+        if (inGroup >= qLimit) {
+          continue;
         }
-      });
+      }
+      admittedIndex = i;
       break;
     }
+
+    if (admittedIndex === -1) break;
+
+    const nextItem = scheduler.queue.splice(admittedIndex, 1)[0];
+    setImmediate(() => {
+      if (!scheduler.isStopped) {
+        scheduler.runTask(nextItem.taskId, nextItem.options || {}).catch((runErr) => {
+          bestEffort('drain-queued-task', () => {}, scheduler.logger);
+        });
+      }
+    });
+    break;
   }
 
   // 1. Structured LLM Actions (#137)

package/lib/scheduler-lifecycle.js

@@ -76,6 +76,9 @@ export function pauseTask(scheduler, taskId, reason = null) {
   const task = scheduler.store.get(taskId);
   if (!task) return null;
   task.status = 'paused';
+  if (task.oneShot) {
+    task.targetTimestamp = task.targetTimestamp || task.nextRunAt;
+  }
   task.nextRunAt = null;
   if (reason) {
     task.pausedReason = reason;

package/lib/scheduler.js

@@ -1,6 +1,8 @@
 import { logger } from './logger.js';
 import { bestEffort } from './best-effort.js';
 import { Cron } from 'croner';
+
+const MAX_TIMEOUT_MS = 2147483647; // 2^31 - 1 ms (~24.85 days)
 import {
   AGENT_TASK_TYPES,
   addUsage,
@@ -128,14 +130,76 @@ function parseIntervalExpression(str) {
   if (!match) return null;
   const num = parseInt(match[1], 10);
   const unit = (match[2] || 'm').toLowerCase();
+  let pattern = null;
+  let humanText = null;
+
   if (unit.startsWith('m')) {
-    return { cronPattern: `*/${num} * * * *`, humanText: `Every ${num} minutes`, isInterval: true };
-  }
-  if (unit.startsWith('h')) {
-    return { cronPattern: `0 */${num} * * *`, humanText: `Every ${num} hours`, isInterval: true };
+    if (num < 1) {
+      throw new Error('Invalid interval: minute interval must be at least 1 minute');
+    }
+    if (num >= 60) {
+      if (num % 60 === 0) {
+        const hours = num / 60;
+        if (hours >= 24 && hours % 24 === 0) {
+          const days = hours / 24;
+          if (days > 31) {
+            throw new Error(`Invalid interval: minute interval "${num}m" (${days} days) exceeds 31 days`);
+          }
+          pattern = `0 0 */${days} * *`;
+          humanText = `Every ${days} days`;
+        } else if (hours > 23) {
+          throw new Error(`Invalid interval: minute interval "${num}m" (${hours} hours) cannot be expressed as a cron step`);
+        } else {
+          pattern = `0 */${hours} * * *`;
+          humanText = `Every ${hours} hours`;
+        }
+      } else {
+        throw new Error(`Invalid interval: minute interval "${num}m" exceeds 59 minutes and is not a multiple of 60. Use hours (e.g. every 2h) or a multiple of 60m`);
+      }
+    } else {
+      pattern = `*/${num} * * * *`;
+      humanText = `Every ${num} minutes`;
+    }
+  } else if (unit.startsWith('h')) {
+    if (num < 1) {
+      throw new Error('Invalid interval: hour interval must be at least 1 hour');
+    }
+    if (num >= 24) {
+      if (num % 24 === 0) {
+        const days = num / 24;
+        if (days > 31) {
+          throw new Error(`Invalid interval: hour interval "${num}h" (${days} days) exceeds 31 days`);
+        }
+        pattern = `0 0 */${days} * *`;
+        humanText = `Every ${days} days`;
+      } else {
+        throw new Error(`Invalid interval: hour interval "${num}h" exceeds 23 hours and is not a multiple of 24. Use days (e.g. every 2d) or a multiple of 24h`);
+      }
+    } else {
+      pattern = `0 */${num} * * *`;
+      humanText = `Every ${num} hours`;
+    }
+  } else if (unit.startsWith('d')) {
+    if (num < 1 || num > 31) {
+      throw new Error(`Invalid interval: day interval "${num}d" must be between 1 and 31 days`);
+    }
+    pattern = `0 0 */${num} * *`;
+    humanText = `Every ${num} days`;
   }
-  if (unit.startsWith('d')) {
-    return { cronPattern: `0 0 */${num} * *`, humanText: `Every ${num} days`, isInterval: true };
+
+  if (pattern) {
+    try {
+      const testJob = new Cron(pattern, { sloppyRanges: true });
+      const next = testJob.nextRun();
+      return {
+        cronPattern: pattern,
+        humanText,
+        isInterval: true,
+        nextRun: next ? next.getTime() : null,
+      };
+    } catch (err) {
+      throw new Error(`Invalid interval pattern "${pattern}": ${err.message}`);
+    }
   }
   return null;
 }
@@ -252,6 +316,7 @@ export class TaskScheduler {
     this.running = new Map();
     this.runCounters = {};
     this.queue = [];
+    this.groupLimits = opts.groupLimits instanceof Map ? opts.groupLimits : new Map(Object.entries(opts.groupLimits || {}));
     this.heartbeatTimer = null;
     this.logger = opts.logger || null;
     this.isStopped = false;
@@ -377,17 +442,34 @@ export class TaskScheduler {
 
   scheduleOneShot(task, parsed) {
     task.oneShot = true;
+    task.targetTimestamp = parsed.targetTimestamp;
     task.nextRunAt = parsed.targetTimestamp;
     this.store.set(task);
 
-    const delay = Math.max(0, parsed.targetTimestamp - Date.now());
-    const timer = setTimeout(() => {
-      this.timers.delete(task.id);
-      this.runTask(task.id).catch((err) => {
-        logger.error(`[dsh-cron] one-shot run of task ${task.id} failed:`, (err && err.message) || err);
-      });
-    }, delay);
-    this.timers.set(task.id, timer);
+    const armTimer = () => {
+      const remaining = parsed.targetTimestamp - Date.now();
+      if (remaining <= 0) {
+        this.timers.delete(task.id);
+        this.runTask(task.id).catch((err) => {
+          logger.error(`[dsh-cron] one-shot run of task ${task.id} failed:`, (err && err.message) || err);
+        });
+        return;
+      }
+      const delay = Math.min(remaining, MAX_TIMEOUT_MS);
+      const timer = setTimeout(() => {
+        if (Date.now() >= parsed.targetTimestamp) {
+          this.timers.delete(task.id);
+          this.runTask(task.id).catch((err) => {
+            logger.error(`[dsh-cron] one-shot run of task ${task.id} failed:`, (err && err.message) || err);
+          });
+        } else {
+          armTimer();
+        }
+      }, delay);
+      this.timers.set(task.id, timer);
+    };
+
+    armTimer();
   }
 
   scheduleCron(task, parsed) {
@@ -416,6 +498,11 @@ export class TaskScheduler {
     try {
       const parsed = parseScheduleExpression(task.schedule);
       if (parsed.isOneShot) {
+        const existingTarget = task.targetTimestamp || task.nextRunAt;
+        if (existingTarget && typeof existingTarget === 'number' && !isNaN(existingTarget)) {
+          parsed.targetTimestamp = existingTarget;
+          parsed.nextRun = existingTarget;
+        }
         this.scheduleOneShot(task, parsed);
         return;
       }
@@ -425,6 +512,25 @@ export class TaskScheduler {
     }
   }
 
+  getGroupLimit(group) {
+    if (!group || group === 'default') return 0;
+    if (this.groupLimits && this.groupLimits.has(group)) {
+      return Number(this.groupLimits.get(group)) || 0;
+    }
+    return 1;
+  }
+
+  getRunningGroupCount(group) {
+    if (!group || group === 'default') return 0;
+    let count = 0;
+    for (const [, run] of this.running.entries()) {
+      if (run.concurrencyGroup === group) {
+        count++;
+      }
+    }
+    return count;
+  }
+
   beginRun(task, taskId, options = {}) {
     return beginRun(this, task, taskId, options);
   }

package/lib/settings.js

@@ -21,7 +21,7 @@ export const Config = z.object({
   onlyOnFailure: z.boolean().default(false).description('Deliver reports only for failed runs').volatile(),
   kanbanBaseUrl: z.string().default('http://127.0.0.1:3000').description('Base URL of the dsh-kanban HTTP API').volatile(),
   defaultTimezone: z.string().default('').description('Default IANA time zone for schedules (empty = server local)').volatile(),
-  maxConcurrent: z.number().default(0).description('Max parallel task runs (0 = unlimited)').volatile(),
+  maxConcurrent: z.number().default(2).description('Max parallel task runs (0 = unlimited, default 2)').volatile(),
   heartbeatUrl: z.string().default('').description('Dead man\'s snitch URL pinged on the heartbeat interval').volatile(),
   heartbeatIntervalSec: z.number().default(0).description('Heartbeat ping interval in seconds (0 = off)').volatile(),
   // --- Delivery channels (#20-#23, #26, #28, #47) ---

package/lib/task-create.js

@@ -66,6 +66,8 @@ export function executeCreateTask(store, scheduler, args) {
     skillName: args.skillName ? String(args.skillName).trim() : '',
     workflowName: args.workflowName ? String(args.workflowName).trim() : '',
     oneShot: Boolean(parsed.isOneShot),
+    targetTimestamp: parsed.isOneShot ? parsed.targetTimestamp : undefined,
+    nextRunAt: parsed.isOneShot ? parsed.targetTimestamp : (parsed.nextRun || undefined),
     costLimitUsd: Number(args.costLimitUsd) > 0 ? Number(args.costLimitUsd) : undefined,
     dailyCostLimitUsd: Number(args.dailyCostLimitUsd) > 0 ? Number(args.dailyCostLimitUsd) : undefined,
     tokenLimit: Number(args.tokenLimit) > 0 ? Number(args.tokenLimit) : undefined,

package/lib/task-patch.js

@@ -67,10 +67,20 @@ export function buildTaskPatch(current, body) {
   if (patch.schedule !== undefined) {
     // An empty schedule would leave an armed task that can never fire.
     if (!String(patch.schedule).trim()) return { ok: false, error: 'Schedule cannot be empty' };
-    const parsed = parseScheduleExpression(patch.schedule);
-    patch.schedule = parsed.cronPattern || patch.schedule;
-    patch.scheduleText = (body && body.scheduleText) || parsed.humanText;
-    patch.oneShot = Boolean(parsed.isOneShot || (body && body.oneShot));
+    try {
+      const parsed = parseScheduleExpression(patch.schedule);
+      const newSchedule = parsed.cronPattern || patch.schedule;
+      const scheduleChanged = newSchedule !== current.schedule;
+      patch.schedule = newSchedule;
+      patch.scheduleText = (body && body.scheduleText) || parsed.humanText;
+      patch.oneShot = Boolean(parsed.isOneShot || (body && body.oneShot));
+      if (scheduleChanged) {
+        patch.nextRunAt = parsed.isOneShot ? parsed.targetTimestamp : (parsed.nextRun || null);
+        patch.targetTimestamp = parsed.isOneShot ? parsed.targetTimestamp : undefined;
+      }
+    } catch (err) {
+      return { ok: false, error: err.message };
+    }
   }
   if (patch.costLimitUsd !== undefined) {
     patch.costLimitUsd = patch.costLimitUsd === null ? null : (Number(patch.costLimitUsd) > 0 ? Number(patch.costLimitUsd) : null);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-cron",
-  "version": "0.2.37",
+  "version": "0.2.39",
   "description": "Background automation runner for DSH: isolated agent runs, script/HTTP/SSH/Docker runtimes, cost guard, notifications, heartbeats.",
   "type": "module",
   "main": "lib/index.js",