@goodandready/dsh-cron 0.2.20 → 0.2.22

package/README.md

@@ -97,6 +97,8 @@ Click the clock icon in the DSH sidebar (positioned next to the new-session butt
 * **1-Click Preset Templates**: scaffold common workflows like *Daily digest*, *Weekly review*, and *Follow-up monitor*.
 * **Execution History**: open any task card to review previous runs — timestamps, durations, statuses (success / failed / timeout / skipped / missed), outputs, and errors.
 * **Aggregated Stats Bar**: live dashboard with active task count, total runs, total token consumption, and the estimated dollar spend.
+* **Quick Schedule Presets**: quickly select standard cadence presets (`15m`, `1h`, `Daily 09:00`, `Weekdays`, `Weekly Mon`) directly within the modal task schedule editor with instant natural-language preview.
+* **Auto-Pause & Burn Guard Badges**: task cards prominently display alert badges when a task is paused by the Token & Cost Burn Guard with the specific reason indicated.
 
 ### 2. "Create with DSH" Dialog
 Transform natural language into a scheduled job without guessing cron syntax:
@@ -159,8 +161,9 @@ Every task picks its own runtime; non-LLM runtimes need no model and consume no
 * **Environment variables** — a per-task `env` map (KEY VALUE per line in the UI) applied to external runtimes; secrets do not belong here.
 * **Workspaces and worktrees** — bind a task to a harness workspace (`workspaceId`) and, for code-modifying agent tasks, run it in an isolated git worktree (`worktree`, `keepWorktree`).
 
-### 7. Cost Control: Fallback Model
-A task can run on the cheap model by default and still finish on the strong one: set `fallbackModel` (and optionally `fallbackProvider`) and a failed run — `error` or `timeout` — is retried **once** on that model before the ordinary retry backoff applies. History records which model produced the result and whether the fallback was used, usage and cost of both attempts are summed, and the `{model}` template variable renders the model that finished the run. Only agent-mediated tasks (`llm`, `skill`, `workflow`) can use a fallback.
+### 7. Cost Control: Fallback Model & Burn Guard
+* **Fallback Model** — A task can run on the cheap model by default and still finish on the strong one: set `fallbackModel` (and optionally `fallbackProvider`) and a failed run — `error` or `timeout` — is retried **once** on that model before the ordinary retry backoff applies. History records which model produced the result and whether the fallback was used, usage and cost of both attempts are summed, and the `{model}` template variable renders the model that finished the run. Only agent-mediated tasks (`llm`, `skill`, `workflow`) can use a fallback.
+* **Token & Cost Burn Guard** — Prevent runaway spending by configuring per-task limits: `costLimitUsd` (lifetime spend limit in USD), `dailyCostLimitUsd` (rolling 24-hour spend limit in USD), and `tokenLimit` (lifetime token limit). If a task exceeds any threshold, execution is halted, the task is automatically paused with `pausedReason` (`cost_limit_exceeded`, `daily_cost_limit_exceeded`, or `token_limit_exceeded`), and an alert notification is dispatched across all active channels.
 
 ### 8. Session Integration & Permissions
 * **Per-task permission presets** — `default`, `read-only`, `workspace-write`, or `full` are applied to the task's agent session before the prompt runs.
@@ -188,6 +191,14 @@ A finished run is delivered to every channel configured for the task — Telegra
 * **Voice** — `dsh-tts` speaks the report through its HTTP route (`ttsBaseUrl`, default `http://127.0.0.1:3080`).
 * **Gitea** — opens an issue with the run report (`giteaBaseUrl`, `giteaRepo`, token credential); failures are labelled `cron`, `bug`, `alert`.
 * **Test dispatch button** — verify Telegram connectivity on the spot before scheduling critical jobs.
+* **Interactive Telegram Bot Commands** — Remotely manage and monitor tasks via Telegram webhook (`/dsh-cron/api/telegram-webhook`):
+  * `/status` — general scheduler health, uptime, active/paused task counts.
+  * `/tasks` — list configured tasks with schedule and state.
+  * `/run <id>` — trigger immediate out-of-order execution of a task.
+  * `/pause <id>` and `/resume <id>` — pause or resume a task schedule.
+  * `/log <id>` — view the most recent run output and execution details.
+  * `/help` — display available bot commands.
+  Configured via incoming webhook and restricted to chat/user IDs specified in `telegramAllowedChatIds`.
 
 ### 12. Kanban Integration & Cost Meter
 * **Automatic Kanban cards** — with `kanbanMode` set to `on_failure` or `always`, the plugin creates cards in `dsh-kanban` (`on_failure` → *Backlog* on `error`/`timeout`; `always` → *Done*/*Backlog* on completion).
@@ -337,7 +348,7 @@ Developer-facing, no behaviour change. `parseScheduleExpression` was split into
 
 ### 22. Automation, Task Chaining & Observability Pack (Added in v0.2.10, #137)
 - **Two-Way Telegram Interactive Controls**: Run completion notifications include inline keyboard buttons (`🚀 Run Now`, `⏸️ Pause` / `▶️ Resume`, `📋 Last Output`). Actions are securely routed via `POST /dsh-cron/telegram/webhook` with Chat ID authorization matching plugin settings or harness defaults.
-- **Task Chaining & Pipelines**: Tasks can declare `onSuccess` and `onFailure` downstream task triggers. Upstream output is automatically forwarded to child tasks via `$DSH_PREV_OUTPUT` environment variable for shell/script tasks and `{{prevOutput}}` variable interpolation in LLM prompts. Infinite execution loops are strictly prevented with a recursion depth limit (max 5 consecutive executions).
+- **Task Chaining Context & Dynamic Variables**: Tasks can declare `onSuccess` and `onFailure` downstream task triggers. Upstream output and execution metadata are forwarded to child tasks via `$DSH_PREV_OUTPUT`, `$DSH_PREV_TASK_ID`, and `$DSH_PREV_STATUS` environment variables for shell tasks, and `{{prev.output}}` (or `{{prevOutput}}`), `{{prev.taskId}}`, and `{{prev.status}}` variable interpolation in LLM prompts. Prompts also support dynamic runtime interpolation for `{{date}}`, `{{time}}`, `{{datetime}}`, `{{timestamp}}`, `{{year}}`, `{{month}}`, `{{day}}`, `{{taskId}}`, `{{taskName}}`, and `{{runCount}}`. Recursion depth is strictly bounded to prevent loops.
 - **Structured LLM Actions**: Autonomous model runs can output structured JSON directives to trigger secondary tasks, dispatch channel notifications, or open issues. Controlled via `llmActionsEnabled: false` settings toggle (strictly disabled by default).
 - **History Archival & Latency Insights**: Active task store retains the most recent 100 runs for instant performance, while older runs are archived in `tasks_archive.json`. New REST endpoints `GET /dsh-cron/tasks/:id/archive` and `GET /dsh-cron/tasks/:id/stats` expose historical records and aggregated latency statistics. Task UI displays execution duration latency badges with color thresholds (<5s green, <30s yellow, >=30s red).
 - **Enriched Prometheus Observability**: The `/dsh-cron/metrics` endpoint exports the active concurrency gauge `dsh_cron_concurrent_running`, per-task prompt/completion token consumption counters `dsh_cron_task_tokens_total{task,model,type}`, and per-task cost estimation counters `dsh_cron_task_cost_usd_total{task,model}`.
@@ -493,6 +504,7 @@ dsh-cron:
 | `pushplusUrl` / `pushplusTokenRef` | `string` | `"https://www.pushplus.plus/send"` / `""` | PushPlus endpoint (override for a self-hosted proxy) and token credential name |
 | `ttsBaseUrl` | `string` | `"http://127.0.0.1:3080"` | Base URL of the `dsh-tts` plugin used for voice announcements |
 | `giteaBaseUrl` / `giteaRepo` / `giteaTokenRef` | `string` | `""` | Gitea channel: base URL, `owner/repo`, and the credential name of the API token |
+| `telegramAllowedChatIds` | `string` | `""` | Comma-separated list of Telegram chat or user IDs authorized to execute interactive bot commands |
 | `apiToken` | `string` | `""` | Bearer token for the external `/dsh-cron/api/*` surface. Stored as a secret field and returned masked; empty disables the surface (503), a wrong value answers 401 |
 
 Notes:

package/README.ru.md

@@ -96,6 +96,8 @@ graph TD
 * **Мгновенные действия**: немедленный запуск (**Запустить**), пауза/возобновление расписания, удаление с подтверждением.
 * **Готовые шаблоны в один клик**: *Ежедневная сводка*, *Еженедельный обзор*, *Мониторинг дальнейших действий*.
 * **История запусков**: в карточке задачи — время, длительность и статусы предыдущих запусков (успех / сбой / таймаут / пропуск / пропущен по простою), вывод и ошибки.
+* **Быстрые пресеты расписания**: выбор типовых интервалов в 1 клик (`15m`, `1h`, `Daily 09:00`, `Weekdays`, `Weekly Mon`) прямо в редакторе расписания с мгновенным обновлением человекопонятного описания.
+* **Бейджи автопаузы и защиты бюджета**: карточки задач наглядно отображают предупреждающий бейдж с точной причиной при автоматической приостановке защитой расходов (Burn Guard) или ручной паузе.
 * **Сводная статистика**: активные задачи, всего запусков, израсходованные токены и оценочная стоимость в долларах.
 
 ### 2. Диалог «Создать с DSH»
@@ -158,8 +160,9 @@ cron_create_task({
 * **Переменные окружения** — карта `env` на задачу (в UI — строки KEY VALUE) для внешних рантаймов; секретам здесь не место.
 * **Workspace и worktree** — привязка задачи к workspace харнесса (`workspaceId`) и, для изменяющих код агентских задач, запуск в изолированном git worktree (`worktree`, `keepWorktree`).
 
-### 7. Экономия: fallback-модель
-Задача может идти на дешёвой модели по умолчанию и всё же завершиться на сильной: задайте `fallbackModel` (и при необходимости `fallbackProvider`), и сбойный запуск (`error` или `timeout`) один раз повторится на этой модели, прежде чем включится обычный retry с задержкой. В истории видно, какая модель произвела результат и был ли использован fallback; расход и стоимость обеих попыток суммируются; переменная шаблона `{model}` подставляет модель, завершившую запуск. Fallback доступен только агентским типам (`llm`, `skill`, `workflow`).
+### 7. Экономия: fallback-модель и защита бюджета (Burn Guard)
+* **Fallback-модель** — задача может идти на дешёвой модели по умолчанию и всё же завершиться на сильной: задайте `fallbackModel` (и при необходимости `fallbackProvider`), и сбойный запуск (`error` или `timeout`) один раз повторится на этой модели, прежде чем включится обычный retry с задержкой. В истории видно, какая модель произвела результат и был ли использован fallback; расход и стоимость обеих попыток суммируются; переменная шаблона `{model}` подставляет модель, завершившую запуск. Fallback доступен только агентским типам (`llm`, `skill`, `workflow`).
+* **Защита бюджета токенов и расходов (Burn Guard)** — предотвращение неконтролируемых трат через индивидуальные лимиты задачи: `costLimitUsd` (общий лимит расходов в USD), `dailyCostLimitUsd` (суточный лимит за последние 24 часа в USD) и `tokenLimit` (лимит суммарных токенов). При превышении любого порога выполнение прекращается, задача автоматически переводится в паузу с фиксацией `pausedReason` (`cost_limit_exceeded`, `daily_cost_limit_exceeded`, `token_limit_exceeded`), а во все активные каналы отправляется тревожное оповещение.
 
 ### 8. Интеграция сессий и права
 * **Permission-пресеты на задачу** — `default`, `read-only`, `workspace-write` или `full` применяются к сессии агента перед запуском промпта.
@@ -213,7 +216,7 @@ cron_create_task({
 
 ### 22. Автоматизация, цепочки задач и наблюдаемость (v0.2.10, #137)
 - **Двухсторонний интерактивный Telegram**: Кнопки действий под уведомлениями (`🚀 Run Now`, `⏸️ Pause`, `📋 Last Output`), вебхук `POST /dsh-cron/telegram/webhook` с валидацией прав по Chat ID и откликом `answerCallbackQuery`.
-- **Цепочки задач и конвейеры**: Триггеры `onSuccess` и `onFailure` для связывания задач. Передача вывода родительской задачи в переменную `$DSH_PREV_OUTPUT` (для shell) и `{{prevOutput}}` (для LLM). Ограничение глубины (максимум 5 уровней) против зацикливания.
+- **Контекст цепочек задач и динамические переменные**: Триггеры `onSuccess` и `onFailure` для связывания задач. Результаты работы и метаданные родительской задачи передаются дочерним через переменные окружения `$DSH_PREV_OUTPUT`, `$DSH_PREV_TASK_ID`, `$DSH_PREV_STATUS` для shell/script задач и через подстановку `{{prev.output}}` (или `{{prevOutput}}`), `{{prev.taskId}}`, `{{prev.status}}` в LLM-промптах. Кроме того, в промптах поддерживаются динамические runtime-переменные: `{{date}}`, `{{time}}`, `{{datetime}}`, `{{timestamp}}`, `{{year}}`, `{{month}}`, `{{day}}`, `{{taskId}}`, `{{taskName}}` и `{{runCount}}`. Глубина рекурсии строго ограничена для защиты от зацикливания.
 - **Структурированные действия LLM**: Парсер директив модели (`trigger_task`, `notify`, `create_issue`) под опцией `llmActionsEnabled: false`.
 - **Архивация и задержка в UI**: REST API `/dsh-cron/tasks/:id/archive` с пагинацией и статистика `/stats`. Бейджи латентности на карточках задач (<5с зелёный, <30с жёлтый, ≥30с красный).
 - **Расширенные Prometheus-метрики**: Gauge `dsh_cron_concurrent_running`, счетчики токенов и стоимости в USD на задачу.
@@ -490,6 +493,7 @@ bash deploy.sh verify [exact-version]
 | `pushplusUrl` / `pushplusTokenRef` | `string` | `"https://www.pushplus.plus/send"` / `""` | Endpoint PushPlus (переопределяется для self-hosted прокси) и имя credential токена |
 | `ttsBaseUrl` | `string` | `"http://127.0.0.1:3080"` | Базовый URL плагина `dsh-tts` для голосовых объявлений |
 | `giteaBaseUrl` / `giteaRepo` / `giteaTokenRef` | `string` | `""` | Канал Gitea: базовый URL, `owner/repo` и имя credential API-токена |
+| `telegramAllowedChatIds` | `string` | `""` | Список chat ID или user ID Telegram через запятую, авторизованных для интерактивных команд бота |
 | `apiToken` | `string` | `""` | Bearer-токен внешней поверхности `/dsh-cron/api/*`. Секретное поле, отдаётся замаскированным; пусто отключает поверхность (503), неверное значение — 401 |
 
 Примечания:

package/README.zh.md

@@ -96,6 +96,8 @@ graph TD
 * **即时操作**：立即运行（**Run Now**）、暂停/恢复调度、带确认的删除。
 * **一键预设模板**：*每日摘要*、*每周回顾*、*待办监控*。
 * **运行历史**：打开任务卡片查看历史运行 —— 时间、耗时、状态（成功 / 失败 / 超时 / 跳过 / 错过）、输出与错误。
+* **快捷计划预设**：在任务编辑弹窗中通过预设按钮一键填入常用频率（`15m`、`1h`、`Daily 09:00`、`Weekdays`、`Weekly Mon`），并即时更新自然语言预览。
+* **自动暂停与预算保护徽章**：当任务因预算熔断机制（Burn Guard）自动暂停或手动暂停时，任务卡片上显著展示包含具体原因的状态徽章。
 * **汇总统计栏**：活跃任务数、总运行次数、总 token 消耗与估算美元成本。
 
 ### 2. “由 DSH 创建”对话框
@@ -158,8 +160,9 @@ cron_create_task({
 * **环境变量** —— 按任务的 `env` 映射（界面中每行 KEY VALUE）应用于外部运行时；请勿在此存放密钥。
 * **工作区与 worktree** —— 将任务绑定到 Harness 工作区（`workspaceId`）；对会修改代码的智能体任务，可在隔离的 git worktree 中运行（`worktree`、`keepWorktree`）。
 
-### 7. 成本控制：回退模型
-任务可以默认使用便宜模型，失败时改用更强模型完成：设置 `fallbackModel`（可选 `fallbackProvider`），失败（`error` 或 `timeout`）的运行会在该模型上重试一次，之后才进入常规重试退避。历史记录会标明最终产出结果的模型以及是否使用了回退，两次尝试的用量与成本都会累计，模板变量 `{model}` 渲染完成运行的模型。回退仅适用于智能体类型（`llm`、`skill`、`workflow`）。
+### 7. 成本控制：回退模型与支出保护（Burn Guard）
+* **回退模型** —— 任务可以默认使用便宜模型，失败时改用更强模型完成：设置 `fallbackModel`（可选 `fallbackProvider`），失败（`error` 或 `timeout`）的运行会在该模型上重试一次，之后才进入常规重试退避。历史记录会标明最终产出结果的模型以及是否使用了回退，两次尝试的用量与成本都会累计，模板变量 `{model}` 渲染完成运行的模型。回退仅适用于智能体类型（`llm`、`skill`、`workflow`）。
+* **Token 与成本支出保护（Burn Guard）** —— 为任务配置严格预算上限：`costLimitUsd`（总支出美元上限）、`dailyCostLimitUsd`（24小时滚动支出上限）和 `tokenLimit`（Token总数上限）。一旦达到任一阈值，任务将自动暂停并记录 `pausedReason`（`cost_limit_exceeded`、`daily_cost_limit_exceeded` 或 `token_limit_exceeded`），同时向所有配置的通知渠道发送报警通知。
 
 ### 8. 会话集成与权限
 * **按任务的权限预设** —— `default`、`read-only`、`workspace-write` 或 `full` 在提示词执行前应用于任务会话。
@@ -336,7 +339,7 @@ bash deploy.sh verify [exact-version]
 
 ### 22. 自动化、任务链与可观测性包（v0.2.10，#137）
 - **Telegram 双向交互控制**：任务通知附带内嵌操作按钮（`🚀 立即运行`、`⏸️ 暂停/恢复`、`📋 最新日志`）。由 `POST /dsh-cron/telegram/webhook` 处理，严格鉴权 Chat ID 并调用 `answerCallbackQuery` 反馈。
-- **任务管道与级联触发**：配置 `onSuccess` 与 `onFailure` 下游触发器。上游输出自动注入子任务环境变量 `$DSH_PREV_OUTPUT`，LLM 任务支持 `{{prevOutput}}` 插值。内置最大 5 级深度递归防护，杜绝死循环。
+- **任务链上下文与动态变量插值**：配置 `onSuccess` 与 `onFailure` 下游触发器。父任务的执行结果与元数据自动传递给子任务，在 Shell 任务中提供 `$DSH_PREV_OUTPUT`、`$DSH_PREV_TASK_ID`、`$DSH_PREV_STATUS` 环境变量，在 LLM Prompt 中支持 `{{prev.output}}`（或 `{{prevOutput}}`）、`{{prev.taskId}}`、`{{prev.status}}` 占位符插值。Prompt 额外支持动态运行时时间与元数据变量：`{{date}}`、`{{time}}`、`{{datetime}}`、`{{timestamp}}`、`{{year}}`、`{{month}}`、`{{day}}`、`{{taskId}}`、`{{taskName}}`、`{{runCount}}`。内置最大 5 级深度递归防护，杜绝死循环。
 - **模型结构化动作指令**：自主分析任务可输出 JSON 指令触发级联任务（`trigger_task`）、定向告警（`notify`）或创建 Issue。受 `llmActionsEnabled: false` 严格保护。
 - **历史归档与延迟洞察**：REST 接口 `GET /dsh-cron/tasks/:id/archive`（支持分页）与 `GET /dsh-cron/tasks/:id/stats`；UI 任务卡片展示耗时彩色徽章（<5s 绿，<30s 黄，≥30s 红）。
 - **Prometheus 监控增强**：`/dsh-cron/metrics` 导出当前活动并发量 `dsh_cron_concurrent_running`、各任务 Token 计数器及成本预估指标。
@@ -490,6 +493,7 @@ dsh-cron:
 | `pushplusUrl` / `pushplusTokenRef` | `string` | `"https://www.pushplus.plus/send"` / `""` | PushPlus 端点（可指向自建代理）与 token 凭据名称 |
 | `ttsBaseUrl` | `string` | `"http://127.0.0.1:3080"` | 用于语音播报的 `dsh-tts` 基础地址 |
 | `giteaBaseUrl` / `giteaRepo` / `giteaTokenRef` | `string` | `""` | Gitea 渠道：基础地址、`owner/repo` 与 API token 的凭据名称 |
+| `telegramAllowedChatIds` | `string` | `""` | 允许执行交互式机器人命令的 Telegram Chat ID 或 User ID（英文逗号分隔） |
 | `apiToken` | `string` | `""` | 外部 `/dsh-cron/api/*` 接口的 Bearer 令牌。保密字段，返回时掩码；为空时接口返回 503，错误值返回 401 |
 
 说明：

package/lib/api-webhook.js

@@ -1,5 +1,7 @@
 import { sendJson, readBody } from './http-utils.js';
 import { answerTelegramCallbackQuery, sendTelegramMessage, getDshDefaultTelegramCredentials } from './telegram.js';
+import { handleTelegramCommand } from './telegram-commands.js';
+import { bestEffort } from './best-effort.js';
 
 const NOT_ALLOWED = { ok: false, error: 'Method not allowed' };
 
@@ -11,9 +13,36 @@ export async function handleTelegramWebhook({ store, scheduler, req, res }) {
   const { body, error } = await readBody(req, res);
   if (error || !body) return;
 
+  const settings = typeof store.getSettings === 'function' ? store.getSettings() : {};
+  const defaults = getDshDefaultTelegramCredentials();
+  const botToken = settings.botToken || defaults.botToken;
+  const allowedChatId = String(settings.chatId || defaults.chatId || '').trim();
+
+  // 1. Text command message (#175)
+  const message = body.message;
+  if (message && typeof message.text === 'string' && message.text.trim().startsWith('/')) {
+    const fromId = String(message.from?.id || '');
+    const chatId = String(message.chat?.id || fromId);
+    if (allowedChatId && chatId !== allowedChatId && fromId !== allowedChatId) {
+      console.warn(`[dsh-cron] unauthorized telegram command from chat ${chatId} / user ${fromId}`);
+      sendJson(res, 403, { ok: false, error: 'Forbidden' });
+      return;
+    }
+    const result = await handleTelegramCommand({
+      store,
+      scheduler,
+      text: message.text,
+      chatId,
+      botToken,
+    });
+    sendJson(res, 200, result || { ok: true });
+    return;
+  }
+
+  // 2. Inline callback query (#137)
   const callbackQuery = body.callback_query;
   if (!callbackQuery) {
-    sendJson(res, 200, { ok: true });
+    sendJson(res, 200, { ok: true, ignored: true });
     return;
   }
 
@@ -22,11 +51,6 @@ export async function handleTelegramWebhook({ store, scheduler, req, res }) {
   const fromId = String(callbackQuery.from?.id || '');
   const chatId = String(callbackQuery.message?.chat?.id || fromId);
 
-  const settings = typeof store.getSettings === 'function' ? store.getSettings() : {};
-  const defaults = getDshDefaultTelegramCredentials();
-  const botToken = settings.botToken || defaults.botToken;
-  const allowedChatId = String(settings.chatId || defaults.chatId || '').trim();
-
   if (allowedChatId && chatId !== allowedChatId && fromId !== allowedChatId) {
     console.warn(`[dsh-cron] unauthorized telegram callback from chat ${chatId} / user ${fromId}`);
     if (botToken) {
@@ -70,19 +94,13 @@ export async function handleTelegramWebhook({ store, scheduler, req, res }) {
     }
   } else if (verb === 'pause') {
     const isPaused = task.status === 'paused';
-    const newStatus = isPaused ? 'active' : 'paused';
-    if (typeof store.update === 'function') {
-      store.update(taskId, { status: newStatus });
-    } else {
-      store.set({ ...task, status: newStatus });
-    }
     if (isPaused) {
-      scheduler.resume(taskId);
+      scheduler.resumeTask(taskId);
       if (botToken) {
         await answerTelegramCallbackQuery({ botToken, callbackQueryId: queryId, text: `▶️ Resumed: ${task.title}` });
       }
     } else {
-      scheduler.pause(taskId);
+      scheduler.pauseTask(taskId, 'Paused via Telegram button');
       if (botToken) {
         await answerTelegramCallbackQuery({ botToken, callbackQueryId: queryId, text: `⏸ Paused: ${task.title}` });
       }
@@ -104,7 +122,9 @@ export async function handleTelegramWebhook({ store, scheduler, req, res }) {
             chatId,
             text: `*Full Output for ${task.title}:*\n\`\`\`\n${summary.slice(0, 3000)}\n\`\`\``,
             parseMode: 'Markdown',
-          }).catch(() => {});
+          }).catch(() => {
+            bestEffort('telegram-full-output', () => {}, scheduler?.logger);
+          });
         }
       }
     }

package/lib/api.js

@@ -432,6 +432,10 @@ 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)),
+    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),
   };
 }
 

package/lib/burn-guard.js

@@ -0,0 +1,153 @@
+import { bestEffort } from './best-effort.js';
+
+/**
+ * Token & Cost Burn Guard (#173).
+ * Monitors task execution cost and token usage to prevent runaway costs
+ * by automatically pausing the offending task and sending an alert.
+ */
+
+/**
+ * Calculate the rolling sum of run costs within the given time window (default 24h).
+ * @param {Array} runs
+ * @param {number} windowMs
+ * @param {number} now
+ * @returns {number}
+ */
+export function calculateRollingCost(runs = [], windowMs = 86400000, now = Date.now()) {
+  const cutoff = now - windowMs;
+  let total = 0;
+  for (const r of runs) {
+    if (r && typeof r.at === 'number' && r.at >= cutoff) {
+      total += Number(r.costUsd) || 0;
+    }
+  }
+  return Number(total.toFixed(6));
+}
+
+/**
+ * Calculate the rolling sum of tokens within the given time window.
+ * @param {Array} runs
+ * @param {number} windowMs
+ * @param {number} now
+ * @returns {number}
+ */
+export function calculateRollingTokens(runs = [], windowMs = 86400000, now = Date.now()) {
+  const cutoff = now - windowMs;
+  let total = 0;
+  for (const r of runs) {
+    if (r && typeof r.at === 'number' && r.at >= cutoff) {
+      const u = r.usage;
+      const tokens = (u?.inputTokens || 0) + (u?.outputTokens || 0) + (u?.cacheReadTokens || 0);
+      total += tokens;
+    }
+  }
+  return total;
+}
+
+/**
+ * Check if a task has exceeded any of its configured budget limits.
+ * @param {object} task
+ * @param {Array} runs
+ * @param {number} now
+ * @returns {{ exceeded: boolean, type?: string, reason?: string, current?: number, limit?: number }}
+ */
+export function checkTaskBudgetLimits(task, runs = [], now = Date.now()) {
+  if (!task) return { exceeded: false };
+
+  // 1. Total cumulative cost limit in USD
+  const costLimit = Number(task.costLimitUsd);
+  if (costLimit > 0) {
+    const totalCost = Number(task.totalCostUsd || 0);
+    if (totalCost >= costLimit) {
+      return {
+        exceeded: true,
+        type: 'costLimitUsd',
+        reason: `Cumulative cost limit exceeded: $${totalCost.toFixed(4)} >= $${costLimit.toFixed(4)}`,
+        current: totalCost,
+        limit: costLimit,
+      };
+    }
+  }
+
+  // 2. Rolling 24h daily cost limit in USD
+  const dailyCostLimit = Number(task.dailyCostLimitUsd);
+  if (dailyCostLimit > 0) {
+    const dailyCost = calculateRollingCost(runs, 86400000, now);
+    if (dailyCost >= dailyCostLimit) {
+      return {
+        exceeded: true,
+        type: 'dailyCostLimitUsd',
+        reason: `24h daily cost limit exceeded: $${dailyCost.toFixed(4)} >= $${dailyCostLimit.toFixed(4)}`,
+        current: dailyCost,
+        limit: dailyCostLimit,
+      };
+    }
+  }
+
+  // 3. Total cumulative token limit
+  const tokenLimit = Number(task.tokenLimit);
+  if (tokenLimit > 0) {
+    const totalTokens = Number(task.totalTokens || 0);
+    if (totalTokens >= tokenLimit) {
+      return {
+        exceeded: true,
+        type: 'tokenLimit',
+        reason: `Token limit exceeded: ${totalTokens} >= ${tokenLimit}`,
+        current: totalTokens,
+        limit: tokenLimit,
+      };
+    }
+  }
+
+  return { exceeded: false };
+}
+
+/**
+ * Format a human-readable alert message for Telegram and notification channels.
+ * @param {object} task
+ * @param {object} guard
+ * @returns {string}
+ */
+export function formatBurnGuardAlert(task, guard) {
+  const title = task?.title || task?.id || 'Unknown task';
+  return `⚠️ [dsh-cron] Task "${title}" auto-paused by Burn Guard: ${guard.reason}`;
+}
+
+/**
+ * Check task budget limits after a run completes. If exceeded, pause the task and alert.
+ * @param {object} scheduler
+ * @param {string} taskId
+ * @param {object} outcome
+ * @returns {Promise<object|null>}
+ */
+export async function checkAndApplyBurnGuard(scheduler, taskId, outcome) {
+  const task = scheduler.store.get(taskId);
+  if (!task || task.status !== 'active') return null;
+
+  const runs = (scheduler.store.history && scheduler.store.history.get(taskId)) || [];
+  const guard = checkTaskBudgetLimits(task, runs);
+  if (!guard.exceeded) return null;
+
+  console.warn(`[dsh-cron] Burn Guard triggered for task "${task.title}" (${taskId}): ${guard.reason}`);
+  scheduler.pauseTask(taskId, guard.reason);
+
+  const alertMessage = formatBurnGuardAlert(task, guard);
+  try {
+    if (typeof scheduler.deliverNotifications === 'function') {
+      const alertRunInfo = {
+        output: alertMessage,
+        error: guard.reason,
+        status: 'error',
+        costUsd: outcome?.costUsd || 0,
+        durationMs: outcome?.durationMs || 0,
+        model: task.model || '',
+      };
+      await scheduler.deliverNotifications({ ...task, status: 'paused', pausedReason: guard.reason }, alertRunInfo);
+    }
+  } catch (err) {
+    bestEffort('burn-guard-notify', () => {}, scheduler.logger);
+  }
+
+  return guard;
+}
+

package/lib/client.js

@@ -2267,7 +2267,8 @@ window.__ModuleLoader__.load({
                         task.targetSessionId ? React.createElement('span', { className: 'dsh-cron-type-tag dsh-cron-tag-session', title: 'Target session: ' + task.targetSessionId + (task.targetSessionReset && task.targetSessionReset !== 'never' ? ' (' + task.targetSessionReset + ')' : '') }, '🧵 ' + task.targetSessionId) : null,
                         task.preflightType && task.preflightType !== 'none' ? React.createElement('span', { className: 'dsh-cron-type-tag dsh-cron-tag-preflight', title: 'Preflight: ' + task.preflightType }, '🛡️ ' + task.preflightType) : null,
                         task.totalCostUsd > 0 ? React.createElement('span', { className: 'dsh-cron-cost-tag' }, '$' + task.totalCostUsd.toFixed(4)) : null,
-                        task.totalTokens > 0 ? React.createElement('span', { className: 'dsh-cron-tokens-tag' }, (task.totalTokens > 1000 ? Math.round(task.totalTokens / 1000) + 'k' : task.totalTokens) + ' tok') : null
+                        task.totalTokens > 0 ? React.createElement('span', { className: 'dsh-cron-tokens-tag' }, (task.totalTokens > 1000 ? Math.round(task.totalTokens / 1000) + 'k' : task.totalTokens) + ' tok') : null,
+                        task.status === 'paused' && task.pausedReason ? React.createElement('span', { className: 'dsh-cron-type-tag dsh-cron-tag-failure', title: task.pausedReason }, '🛑 ' + task.pausedReason) : null
                       ),
                       React.createElement('div', { className: 'dsh-cron-task-sched' },
                         task.scheduleText || task.schedule,
@@ -2513,6 +2514,21 @@ window.__ModuleLoader__.load({
                       placeholder: T_KEY(t, 'form.schedulePlaceholder'),
                       onChange: (e) => setFormSchedule(e.target.value)
                     }),
+                    React.createElement('div', { style: { display: 'flex', gap: '5px', flexWrap: 'wrap', marginTop: '5px' } },
+                      [
+                        { label: '15m', expr: '*/15 * * * *' },
+                        { label: '1h', expr: '0 * * * *' },
+                        { label: 'Daily 09:00', expr: '0 9 * * *' },
+                        { label: 'Weekdays', expr: '0 9 * * 1-5' },
+                        { label: 'Weekly Mon', expr: '0 9 * * 1' },
+                      ].map((p) => React.createElement('button', {
+                        key: p.label,
+                        type: 'button',
+                        className: 'dsh-cron-btn-secondary',
+                        style: { padding: '2px 7px', fontSize: '11px', borderRadius: '4px' },
+                        onClick: () => { setFormSchedule(p.expr); handlePreviewSchedule(p.expr); }
+                      }, p.label))
+                    ),
                     React.createElement('div', { style: { display: 'flex', gap: '8px', alignItems: 'center', marginTop: '6px' } },
                       React.createElement('button', {
                         type: 'button',
@@ -3364,7 +3380,7 @@ window.__ModuleLoader__.load({
       const [updateState, setUpdateState] = React.useState({
         checking: false,
         updating: false,
-        currentVersion: '0.2.19',
+        currentVersion: '0.2.22',
         latestVersion: undefined,
         updateAvailable: false,
         notice: null,
@@ -4052,8 +4068,23 @@ window.__ModuleLoader__.load({
       function SettingsCardWithBoundary(props) {
         return React.createElement(ErrorBoundary, null, CronSettingsCard(props));
       }
-      // Row seat first (the seat the current core renders), legacy settings.plugin.item
-      // after it as a fallback (#102: still no top-level section fallback).
+      // List seat (plugins.item): the seat the Plugins page renders as the plugin's own
+      // page with its configuration. The label is a static string on purpose — it is
+      // resolved while the page renders, and a locale lookup there would take the whole
+      // client batch down with it.
+      const itemOk = registerIntoMount(ctx, 'plugins.item', {
+        name: 'plugins.item',
+        id: ROW_ID,
+        order: 60,
+        label: () => 'Cron',
+        locale: NS,
+        inject: () => ({ ctx, toggle }),
+      }, SettingsCardWithBoundary);
+      if (!itemOk) {
+        console.warn('[dsh-cron] plugins.item slot unavailable — plugin page card not registered');
+      }
+      // Row seat and the legacy settings.plugin.item seat stay as fallbacks
+      // (#102: still no top-level section fallback).
       const rowOk = registerIntoMount(ctx, 'plugins.row.config', {
         name: 'plugins.row.config',
         key: ROW_CONFIG_KEY,

package/lib/prompt-interpolation.js

@@ -0,0 +1,102 @@
+import { formatDuration } from './templates.js';
+
+function formatDate(d) {
+  const year = d.getUTCFullYear();
+  const month = String(d.getUTCMonth() + 1).padStart(2, '0');
+  const day = String(d.getUTCDate()).padStart(2, '0');
+  return `${year}-${month}-${day}`;
+}
+
+function formatTime(d) {
+  const hours = String(d.getUTCHours()).padStart(2, '0');
+  const minutes = String(d.getUTCMinutes()).padStart(2, '0');
+  const seconds = String(d.getUTCSeconds()).padStart(2, '0');
+  return `${hours}:${minutes}:${seconds}`;
+}
+
+/**
+ * Build dictionary of prompt interpolation variables for a task and run options.
+ */
+export function buildPromptContext(task = {}, options = {}) {
+  const now = options.now instanceof Date ? options.now : new Date();
+  const prevOutput = options.prevOutput != null ? String(options.prevOutput) : '';
+  const prevStatus = options.prevStatus != null ? String(options.prevStatus) : '';
+  const prevTaskId = options.prevTaskId != null ? String(options.prevTaskId) : '';
+  const prevDuration = formatDuration(options.prevDurationMs);
+  const prevCost = options.prevCostUsd != null ? `$${Number(options.prevCostUsd || 0).toFixed(4)}` : '';
+
+  return {
+    // Chaining context
+    'prev.output': prevOutput,
+    'prev_output': prevOutput,
+    'prev.status': prevStatus,
+    'prev_status': prevStatus,
+    'prev.taskId': prevTaskId,
+    'prev.task_id': prevTaskId,
+    'prev_task_id': prevTaskId,
+    'prev.duration': prevDuration,
+    'prev_duration': prevDuration,
+    'prev.cost': prevCost,
+    'prev_cost': prevCost,
+
+    // Time context
+    'date': formatDate(now),
+    'time': formatTime(now),
+    'now': now.toISOString(),
+    'datetime': now.toISOString(),
+    'iso': now.toISOString(),
+    'timestamp': String(now.getTime()),
+
+    // Task metadata
+    'task.id': task.id || '',
+    'task_id': task.id || '',
+    'task.title': task.title || '',
+    'task_title': task.title || '',
+  };
+}
+
+/**
+ * Replace {{var}} or {var} placeholders with values from context.
+ * Supports dot notation like {{prev.output}}. Unknown variables are left untouched.
+ */
+export function interpolateTaskPrompt(text, context = {}) {
+  if (typeof text !== 'string') return text;
+  if (!text) return '';
+
+  return text.replace(/\{\{([a-zA-Z0-9_.]+)\}\}/g, (match, varName) => {
+    if (Object.prototype.hasOwnProperty.call(context, varName)) {
+      const val = context[varName];
+      return val == null ? '' : String(val);
+    }
+    return match;
+  }).replace(/\{([a-zA-Z0-9_.]+)\}/g, (match, varName) => {
+    if (Object.prototype.hasOwnProperty.call(context, varName)) {
+      const val = context[varName];
+      return val == null ? '' : String(val);
+    }
+    return match;
+  });
+}
+
+/**
+ * Resolve a task copy with interpolated prompt and executable fields.
+ */
+export function resolveTaskForExecution(task, options = {}) {
+  if (!task || typeof task !== 'object') return task;
+  const context = buildPromptContext(task, options);
+
+  const resolved = { ...task };
+  if (typeof resolved.prompt === 'string') {
+    resolved.prompt = interpolateTaskPrompt(resolved.prompt, context);
+  }
+  if (typeof resolved.script === 'string') {
+    resolved.script = interpolateTaskPrompt(resolved.script, context);
+  }
+  if (typeof resolved.command === 'string') {
+    resolved.command = interpolateTaskPrompt(resolved.command, context);
+  }
+  if (typeof resolved.url === 'string') {
+    resolved.url = interpolateTaskPrompt(resolved.url, context);
+  }
+  return resolved;
+}

package/lib/scheduler-execution.js

@@ -1,3 +1,5 @@
+import { checkAndApplyBurnGuard } from './burn-guard.js';
+import { resolveTaskForExecution } from './prompt-interpolation.js';
 import { bestEffort } from './best-effort.js';
 import { exec } from 'node:child_process';
 import fs from 'node:fs';
@@ -92,8 +94,9 @@ export async function executeOnce(scheduler, task, signal, options = {}) {
     fallback: false,
   };
   if (typeof scheduler.executeFn !== 'function') return result;
+  const executableTask = resolveTaskForExecution(task, options);
   try {
-    const res = await scheduler.executeFn(task, { signal, ...options });
+    const res = await scheduler.executeFn(executableTask, { signal, ...options });
     if (typeof res === 'object' && res !== null) {
       result.output = res.output || '';
       result.usage = res.usage || result.usage;
@@ -431,6 +434,9 @@ export async function handleCompleteRun(scheduler, task, taskId, currentRun, out
   if (!silent.skipped) await scheduler.deliverNotifications(task, runInfo);
   scheduler.finishRun(task, taskId, outcome.status, queuedCount);
 
+  const guard = await checkAndApplyBurnGuard(scheduler, taskId, outcome);
+  if (guard && guard.exceeded) return;
+
   while (scheduler.queue.length > 0 && scheduler.running.size < scheduler.maxConcurrent) {
     const nextItem = scheduler.queue.shift();
     if (!nextItem) break;
@@ -480,6 +486,9 @@ export async function handleCompleteRun(scheduler, task, taskId, currentRun, out
           chainDepth: currentDepth + 1,
           prevOutput: outcome.output || outcome.error || '',
           prevTaskId: task.id,
+          prevStatus: outcome.status,
+          prevDurationMs: Date.now() - start,
+          prevCostUsd: outcome.costUsd || 0,
         }).catch((err) => {
           console.warn(`[dsh-cron] chained task ${targetId} failed to trigger:`, err.message);
         });

package/lib/scheduler-lifecycle.js

@@ -71,11 +71,14 @@ export async function checkHeartbeats(scheduler) {
 /**
  * Pause a task and abort any active execution.
  */
-export function pauseTask(scheduler, taskId) {
+export function pauseTask(scheduler, taskId, reason = null) {
   const task = scheduler.store.get(taskId);
   if (!task) return null;
   task.status = 'paused';
   task.nextRunAt = null;
+  if (reason) {
+    task.pausedReason = reason;
+  }
   scheduler.clearRetryTimer(taskId);
   if (scheduler.jobs.has(taskId)) {
     scheduler.jobs.get(taskId).stop();
@@ -123,6 +126,7 @@ export function resumeTask(scheduler, taskId) {
   const task = scheduler.store.get(taskId);
   if (!task) return null;
   task.status = 'active';
+  delete task.pausedReason;
   scheduler.scheduleTask(task);
   scheduler.store.set(task);
   return task;

package/lib/scheduler.js

@@ -503,8 +503,8 @@ export class TaskScheduler {
     return finishRun(this, task, taskId, status, queuedCount);
   }
 
-  pauseTask(taskId) {
-    return pauseTask(this, taskId);
+  pauseTask(taskId, reason) {
+    return pauseTask(this, taskId, reason);
   }
 
   removeTask(taskId) {

package/lib/task-create.js

@@ -49,6 +49,9 @@ export function executeCreateTask(store, scheduler, args) {
     skillName: args.skillName ? String(args.skillName).trim() : '',
     workflowName: args.workflowName ? String(args.workflowName).trim() : '',
     oneShot: Boolean(parsed.isOneShot),
+    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,
   });
   scheduler.scheduleTask(task);
   return {

package/lib/task-patch.js

@@ -51,6 +51,15 @@ export function buildTaskPatch(current, body) {
     patch.scheduleText = (body && body.scheduleText) || parsed.humanText;
     patch.oneShot = Boolean(parsed.isOneShot || (body && body.oneShot));
   }
+  if (patch.costLimitUsd !== undefined) {
+    patch.costLimitUsd = patch.costLimitUsd === null ? null : (Number(patch.costLimitUsd) > 0 ? Number(patch.costLimitUsd) : null);
+  }
+  if (patch.dailyCostLimitUsd !== undefined) {
+    patch.dailyCostLimitUsd = patch.dailyCostLimitUsd === null ? null : (Number(patch.dailyCostLimitUsd) > 0 ? Number(patch.dailyCostLimitUsd) : null);
+  }
+  if (patch.tokenLimit !== undefined) {
+    patch.tokenLimit = patch.tokenLimit === null ? null : (Number(patch.tokenLimit) > 0 ? Number(patch.tokenLimit) : null);
+  }
   return { ok: true, patch };
 }
 

package/lib/task-transfer.js

@@ -70,10 +70,14 @@ export const PATCHABLE_TASK_FIELDS = [
   'template',
   'status',
   'oneShot',
+  'costLimitUsd',
+  'dailyCostLimitUsd',
+  'tokenLimit',
+  'pausedReason',
 ];
 
 /** Fields a duplicate inherits; anything else is runtime state, not config. */
-export const DUPLICATE_TASK_FIELDS = PATCHABLE_TASK_FIELDS.filter((key) => key !== 'status');
+export const DUPLICATE_TASK_FIELDS = PATCHABLE_TASK_FIELDS.filter((key) => key !== 'status' && key !== 'pausedReason');
 
 /**
  * Task ids that would shadow the collection routes under /dsh-cron/tasks.

package/lib/telegram-commands.js

@@ -0,0 +1,277 @@
+import { sendTelegramMessage } from './telegram.js';
+import { calculateRollingCost, calculateRollingTokens } from './burn-guard.js';
+import { bestEffort } from './best-effort.js';
+
+/**
+ * Parse a text string into a Telegram bot command and its arguments (#175).
+ * Strips leading slash and bot username suffix (e.g. /status@bot_name -> status).
+ * @param {string} text
+ * @returns {{ command: string, args: string[], raw: string } | null}
+ */
+export function parseTelegramCommand(text) {
+  if (!text || typeof text !== 'string') return null;
+  const trimmed = text.trim();
+  if (!trimmed.startsWith('/')) return null;
+
+  const [cmdToken, ...args] = trimmed.split(/\s+/);
+  const command = cmdToken.slice(1).split('@')[0].toLowerCase();
+  if (!command) return null;
+
+  return { command, args, raw: trimmed };
+}
+
+/**
+ * Format status message for /status command.
+ */
+export function formatStatusMessage({ store, scheduler }) {
+  const tasks = (typeof store?.list === 'function' ? store.list() : []) || [];
+  const active = tasks.filter((t) => t.status === 'active').length;
+  const paused = tasks.filter((t) => t.status === 'paused').length;
+  const running = typeof scheduler?.runningCount === 'function' ? scheduler.runningCount() : 0;
+
+  const runningNames = [];
+  if (scheduler?.running) {
+    for (const id of scheduler.running.keys()) {
+      const t = store.get(id);
+      runningNames.push(t ? t.title : id);
+    }
+  }
+
+  let dailyCost = 0;
+  let dailyTokens = 0;
+  const now = Date.now();
+  if (store?.history) {
+    for (const [, runs] of store.history.entries()) {
+      dailyCost += calculateRollingCost(runs, 86400000, now);
+      dailyTokens += calculateRollingTokens(runs, 86400000, now);
+    }
+  }
+
+  const stats = typeof store?.getAggregatedStats === 'function' ? store.getAggregatedStats() : {};
+
+  const lines = [
+    '📊 *DSH Cron — Scheduler Status*',
+    '',
+    '⚙️ *Tasks:*',
+    `• Total: ${tasks.length}`,
+    `• Active: 🟢 ${active}`,
+    `• Paused: ⏸ ${paused}`,
+    `• Running now: 🔄 ${running}${runningNames.length ? ' (' + runningNames.join(', ') + ')' : ''}`,
+    '',
+    '💰 *Cost & Tokens (last 24 hours):*',
+    `• Estimated cost: $${dailyCost.toFixed(4)}`,
+    `• Tokens: ${dailyTokens.toLocaleString()}`,
+    '',
+    '📈 *History totals:*',
+    `• Total runs: ${stats.totalRuns || 0}`,
+    `• Succeeded: ${stats.successfulRuns || 0}`,
+    `• Failed: ${stats.failedRuns || 0}`,
+  ];
+
+  return lines.join('\n');
+}
+
+/**
+ * Format tasks list message for /tasks command.
+ */
+export function formatTasksMessage(tasks, scheduler) {
+  if (!tasks || !tasks.length) {
+    return '📋 *DSH Cron Tasks:*\n\nTask list is empty.';
+  }
+
+  const items = tasks.slice(0, 20).map((t) => {
+    const isRunning = typeof scheduler?.isRunning === 'function' && scheduler.isRunning(t.id);
+    const statusIcon = isRunning ? '🔄' : (t.status === 'active' ? '🟢' : '⏸');
+    const next = t.nextRunAt
+      ? new Date(t.nextRunAt).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })
+      : (t.status === 'paused' ? 'paused' : '—');
+    const reason = t.pausedReason ? ` (${t.pausedReason.slice(0, 40)})` : '';
+    return `${statusIcon} *${t.title || 'Untitled'}* (\`${t.id}\`)\n   ⏰ ${t.scheduleText || t.schedule || '—'} | next: ${next}${reason}`;
+  });
+
+  const lines = [
+    '📋 *DSH Cron Tasks:*',
+    '',
+    ...items,
+  ];
+
+  if (tasks.length > 20) {
+    lines.push('', `_...and ${tasks.length - 20} more tasks_`);
+  }
+
+  return lines.join('\n\n');
+}
+
+/**
+ * Find a task by id or partial match.
+ */
+function findTask(store, query) {
+  if (!query || typeof store?.get !== 'function') return null;
+  const q = String(query).trim();
+  const direct = store.get(q);
+  if (direct) return direct;
+
+  const list = typeof store.list === 'function' ? store.list() : [];
+  return list.find((t) => t.id.toLowerCase() === q.toLowerCase() || t.title.toLowerCase() === q.toLowerCase()) || null;
+}
+
+/**
+ * Dispatch and handle a Telegram text command.
+ */
+export async function handleTelegramCommand({
+  store,
+  scheduler,
+  text,
+  chatId,
+  botToken,
+  fetchFn = globalThis.fetch,
+}) {
+  const parsed = parseTelegramCommand(text);
+  if (!parsed) return { ok: false, error: 'Not a command' };
+
+  const { command, args } = parsed;
+
+  const reply = async (msgText, replyMarkup) => {
+    if (!botToken || !chatId) return;
+    try {
+      await sendTelegramMessage({
+        botToken,
+        chatId,
+        text: msgText,
+        parseMode: 'Markdown',
+        replyMarkup,
+        fetchFn,
+      });
+    } catch (err) {
+      bestEffort('telegram-cmd-reply', () => {}, scheduler?.logger);
+    }
+  };
+
+  switch (command) {
+    case 'start':
+    case 'help': {
+      const help = [
+        '🤖 *DSH Cron Control Commands:*',
+        '',
+        '• `/status` — summary of daemon status, tasks and 24h cost',
+        '• `/tasks` — list of configured tasks and schedules',
+        '• `/run <id>` — trigger immediate manual execution',
+        '• `/pause <id>` — pause a scheduled task',
+        '• `/resume <id>` — resume a paused task',
+        '• `/log <id>` — show output from the last execution',
+        '• `/help` — this help reference',
+      ].join('\n');
+      await reply(help);
+      return { ok: true, command };
+    }
+
+    case 'status': {
+      const statusText = formatStatusMessage({ store, scheduler });
+      await reply(statusText);
+      return { ok: true, command };
+    }
+
+    case 'tasks': {
+      const tasks = typeof store?.list === 'function' ? store.list() : [];
+      const tasksText = formatTasksMessage(tasks, scheduler);
+      await reply(tasksText);
+      return { ok: true, command };
+    }
+
+    case 'run': {
+      const targetId = args[0];
+      if (!targetId) {
+        await reply('⚠️ *Please specify task ID:*\n`/run <task_id>`');
+        return { ok: false, error: 'Missing task id' };
+      }
+      const task = findTask(store, targetId);
+      if (!task) {
+        await reply(`❌ Task \`${targetId}\` not found.`);
+        return { ok: false, error: 'Task not found' };
+      }
+      try {
+        await scheduler.triggerManualRun(task.id);
+        await reply(`🚀 Triggered immediate execution for *${task.title}* (\`${task.id}\`)`);
+        return { ok: true, command, taskId: task.id };
+      } catch (err) {
+        await reply(`❌ Execution error for *${task.title}*: ${err.message}`);
+        return { ok: false, error: err.message };
+      }
+    }
+
+    case 'pause': {
+      const targetId = args[0];
+      if (!targetId) {
+        await reply('⚠️ *Please specify task ID:*\n`/pause <task_id>`');
+        return { ok: false, error: 'Missing task id' };
+      }
+      const task = findTask(store, targetId);
+      if (!task) {
+        await reply(`❌ Task \`${targetId}\` not found.`);
+        return { ok: false, error: 'Task not found' };
+      }
+      scheduler.pauseTask(task.id, 'Paused via Telegram');
+      await reply(`⏸ Task *${task.title}* (\`${task.id}\`) paused.`);
+      return { ok: true, command, taskId: task.id };
+    }
+
+    case 'resume': {
+      const targetId = args[0];
+      if (!targetId) {
+        await reply('⚠️ *Please specify task ID:*\n`/resume <task_id>`');
+        return { ok: false, error: 'Missing task id' };
+      }
+      const task = findTask(store, targetId);
+      if (!task) {
+        await reply(`❌ Task \`${targetId}\` not found.`);
+        return { ok: false, error: 'Task not found' };
+      }
+      scheduler.resumeTask(task.id);
+      await reply(`▶️ Task *${task.title}* (\`${task.id}\`) resumed.`);
+      return { ok: true, command, taskId: task.id };
+    }
+
+    case 'log': {
+      const targetId = args[0];
+      if (!targetId) {
+        await reply('⚠️ *Please specify task ID:*\n`/log <task_id>`');
+        return { ok: false, error: 'Missing task id' };
+      }
+      const task = findTask(store, targetId);
+      if (!task) {
+        await reply(`❌ Task \`${targetId}\` not found.`);
+        return { ok: false, error: 'Task not found' };
+      }
+      const history = typeof store.getHistory === 'function' ? store.getHistory(task.id, 1) : [];
+      const lastRun = history && history[0];
+      if (!lastRun) {
+        await reply(`ℹ️ No recorded runs for task *${task.title}*.`);
+        return { ok: true, command, empty: true };
+      }
+
+      const isSuccess = lastRun.status === 'success';
+      const statusIcon = isSuccess ? '✅' : '❌';
+      const costStr = lastRun.costUsd > 0 ? ` | $${lastRun.costUsd.toFixed(4)}` : '';
+      const content = lastRun.error || lastRun.output || 'Empty output';
+      const snippet = content.slice(0, 1500);
+
+      const logMsg = [
+        `📄 *Last run log: ${task.title}*`,
+        `*Status:* ${statusIcon} ${lastRun.status} (${lastRun.durationMs}ms${costStr})`,
+        '',
+        '```',
+        snippet,
+        '```',
+      ].join('\n');
+
+      await reply(logMsg);
+      return { ok: true, command, taskId: task.id };
+    }
+
+    default: {
+      await reply(`❓ Unknown command \`/${command}\`. Type /help for assistance.`);
+      return { ok: false, error: 'Unknown command' };
+    }
+  }
+}
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-cron",
-  "version": "0.2.20",
+  "version": "0.2.22",
   "description": "Scheduled cron tasks, background automation and agent execution for DeepSeek Harness.",
   "type": "module",
   "main": "lib/index.js",