@goodandready/dsh-cron 0.3.0 → 0.3.1

package/lib/client.js

@@ -288,14 +288,12 @@ window.__ModuleLoader__.load({
         'settings.kanbanUrlLabel': 'Kanban Base URL',
         'settings.globalNotify': 'Deliver reports of all tasks to Telegram globally',
         'settings.globalOnlyFailure': 'Global mode: only on failures (silent on success)',
-        'settings.testTelegram': '🔔 Test Telegram delivery',
-        'settings.testKanban': '📋 Test Kanban',
-        'settings.sending': 'Sending...',
-        'settings.checkingKanban': 'Checking Kanban...',
-        'settings.testOk': '✅ Test message delivered to Telegram!',
-        'settings.testFail': '❌ {error}',
-        'settings.kanbanOk': '✅ Kanban card created',
-        'settings.kanbanFail': '❌ {error}',
+        'settings.dynamicCredentials': 'Dynamic Credentials Resolution (credential://...)',
+        'settings.dynamicCredentialsHint': 'Resolve credential://... in memory from harness credentials at runtime (#335)',
+        'settings.testTelegram': '🔔 Test Telegram delivery', 'settings.testKanban': '📋 Test Kanban',
+        'settings.sending': 'Sending...', 'settings.checkingKanban': 'Checking Kanban...',
+        'settings.testOk': '✅ Test message delivered to Telegram!', 'settings.testFail': '❌ {error}',
+        'settings.kanbanOk': '✅ Kanban card created', 'settings.kanbanFail': '❌ {error}',
         'settings.save': 'Save settings',
         'settings.saved': '✓ Saved',
         'settings.saveError': 'Save failed: {error}',
@@ -590,14 +588,12 @@ window.__ModuleLoader__.load({
         'settings.kanbanUrlLabel': 'Kanban 服务基础地址',
         'settings.globalNotify': '全局开启所有任务结果推送至 Telegram',
         'settings.globalOnlyFailure': '全局模式：仅在失败时推送 (成功静默)',
-        'settings.testTelegram': '🔔 测试 Telegram 发送',
-        'settings.testKanban': '📋 测试 Kanban',
-        'settings.sending': '正在发送...',
-        'settings.checkingKanban': '正在连接 Kanban...',
-        'settings.testOk': '✅ 测试消息已成功发送至 Telegram！',
-        'settings.testFail': '❌ 发送失败: {error}',
-        'settings.kanbanOk': '✅ Kanban 卡片创建成功',
-        'settings.kanbanFail': '❌ {error}',
+        'settings.dynamicCredentials': '动态凭据解析 (credential://...)',
+        'settings.dynamicCredentialsHint': '运行时从凭据服务动态解析 credential://... 且不泄露到存储 (#335)',
+        'settings.testTelegram': '🔔 测试 Telegram 发送', 'settings.testKanban': '📋 测试 Kanban',
+        'settings.sending': '正在发送...', 'settings.checkingKanban': '正在连接 Kanban...',
+        'settings.testOk': '✅ 测试消息已成功发送至 Telegram！', 'settings.testFail': '❌ 发送失败: {error}',
+        'settings.kanbanOk': '✅ Kanban 卡片创建成功', 'settings.kanbanFail': '❌ {error}',
         'settings.save': '保存设置',
         'settings.saved': '✓ 已保存',
         'settings.saveError': '保存失败: {error}',
@@ -3798,6 +3794,7 @@ window.__ModuleLoader__.load({
       const [notify, setNotify] = React.useState(false);
       const [onlyFailure, setOnlyFailure] = React.useState(false);
       const [llmActionsEnabled, setLlmActionsEnabled] = React.useState(false);
+      const [enableDynamicCredentials, setEnableDynamicCredentials] = React.useState(false);
       const [kanbanUrl, setKanbanUrl] = React.useState('http://127.0.0.1:3000');
       const [delivery, setDelivery] = React.useState({});
       const [sections, setSections] = React.useState({ channels: true });
@@ -3878,6 +3875,7 @@ window.__ModuleLoader__.load({
               setNotify(Boolean(data.settings.notifyTelegram));
               setOnlyFailure(Boolean(data.settings.onlyOnFailure));
               setLlmActionsEnabled(Boolean(data.settings.llmActionsEnabled));
+              setEnableDynamicCredentials(Boolean(data.settings.enableDynamicCredentials));
               setKanbanUrl(data.settings.kanbanBaseUrl || 'http://127.0.0.1:3000');
               setDelivery(pickDeliverySettings(data.settings));
               setHasDefault(Boolean(data.settings.hasDefaultCredentials));
@@ -3905,6 +3903,7 @@ window.__ModuleLoader__.load({
               notifyTelegram: notify,
               onlyOnFailure: onlyFailure,
               llmActionsEnabled: llmActionsEnabled,
+              enableDynamicCredentials: enableDynamicCredentials,
               kanbanBaseUrl: kanbanUrl
             }, delivery))
           });
@@ -4046,6 +4045,14 @@ window.__ModuleLoader__.load({
                 onChange: (e) => setLlmActionsEnabled(e.target.checked)
               }),
               React.createElement('span', null, 'Enable Structured LLM Actions (trigger tasks, notify, create issues)')
+            ),
+            React.createElement('label', { className: 'dsh-cron-checkbox-row' },
+              React.createElement('input', {
+                type: 'checkbox',
+                checked: enableDynamicCredentials,
+                onChange: (e) => setEnableDynamicCredentials(e.target.checked)
+              }),
+              React.createElement('span', null, T_KEY(t, 'settings.dynamicCredentials'))
             )
           ),
           ...renderDeliverySettings({

package/lib/prompt-interpolation.js

@@ -25,6 +25,11 @@ export function buildPromptContext(task = {}, options = {}) {
   const prevDuration = formatDuration(options.prevDurationMs);
   const prevCost = options.prevCostUsd != null ? `$${Number(options.prevCostUsd || 0).toFixed(4)}` : '';
 
+  const filePath = options.filePath != null ? String(options.filePath) : '';
+  const fileName = options.fileName != null ? String(options.fileName) : '';
+  const fileSize = options.fileSize != null ? String(options.fileSize) : '';
+  const fileEvent = options.fileEvent != null ? String(options.fileEvent) : '';
+
   return {
     // Chaining context
     'prev.output': prevOutput,
@@ -39,6 +44,20 @@ export function buildPromptContext(task = {}, options = {}) {
     'prev.cost': prevCost,
     'prev_cost': prevCost,
 
+    // File watcher context (#327)
+    'filePath': filePath,
+    'file.path': filePath,
+    'file_path': filePath,
+    'fileName': fileName,
+    'file.name': fileName,
+    'file_name': fileName,
+    'fileSize': fileSize,
+    'file.size': fileSize,
+    'file_size': fileSize,
+    'fileEvent': fileEvent,
+    'file.event': fileEvent,
+    'file_event': fileEvent,
+
     // Time context
     'date': formatDate(now),
     'time': formatTime(now),

package/lib/runner.js

@@ -1,6 +1,7 @@
 import { logger } from './logger.js';
 import { bestEffort } from './best-effort.js';
 import { estimateTokenCost } from './integrations.js';
+import { resolveDynamicCredentialsInText, resolveDynamicCredentialsInObject } from './secrets.js';
 import {
   EXTERNAL_RUNTIMES,
   normalizeTaskType,
@@ -144,7 +145,104 @@ export class SessionRunner {
   async _run(task, signal, options = {}) {
     logger.info(`[dsh-cron] executing task "${task.title}" (${task.id})`);
 
-    // 1. Non-LLM runtimes: shell, Node.js, Python, HTTP, SSH, Docker (#4 #5 #7 #8 #9)
+    // Dynamic credentials resolution in-memory (#335)
+    let effectiveTask = task;
+    const resolvedSecrets = [];
+    const settings = (this.store && typeof this.store.getSettings === 'function')
+      ? this.store.getSettings()
+      : {};
+
+    if (settings.enableDynamicCredentials) {
+      effectiveTask = { ...task };
+      if (typeof effectiveTask.prompt === 'string') {
+        const res = await resolveDynamicCredentialsInText(effectiveTask.prompt, this.ctx);
+        effectiveTask.prompt = res.text;
+        resolvedSecrets.push(...res.resolvedSecrets);
+      }
+      if (typeof effectiveTask.script === 'string') {
+        const res = await resolveDynamicCredentialsInText(effectiveTask.script, this.ctx);
+        effectiveTask.script = res.text;
+        resolvedSecrets.push(...res.resolvedSecrets);
+      }
+      if (typeof effectiveTask.command === 'string') {
+        const res = await resolveDynamicCredentialsInText(effectiveTask.command, this.ctx);
+        effectiveTask.command = res.text;
+        resolvedSecrets.push(...res.resolvedSecrets);
+      }
+      if (typeof effectiveTask.httpUrl === 'string') {
+        const res = await resolveDynamicCredentialsInText(effectiveTask.httpUrl, this.ctx);
+        effectiveTask.httpUrl = res.text;
+        resolvedSecrets.push(...res.resolvedSecrets);
+      }
+      if (typeof effectiveTask.httpBody === 'string') {
+        const res = await resolveDynamicCredentialsInText(effectiveTask.httpBody, this.ctx);
+        effectiveTask.httpBody = res.text;
+        resolvedSecrets.push(...res.resolvedSecrets);
+      }
+      if (effectiveTask.httpHeaders) {
+        const res = await resolveDynamicCredentialsInObject(effectiveTask.httpHeaders, this.ctx);
+        effectiveTask.httpHeaders = res.data;
+        resolvedSecrets.push(...res.resolvedSecrets);
+      }
+      if (effectiveTask.env) {
+        const res = await resolveDynamicCredentialsInObject(effectiveTask.env, this.ctx);
+        effectiveTask.env = res.data;
+        resolvedSecrets.push(...res.resolvedSecrets);
+      }
+    }
+
+    const maskSecrets = (result) => {
+      if (!result || typeof result !== 'object') return result;
+      if (resolvedSecrets.length > 0 && typeof result.output === 'string') {
+        let out = result.output;
+        for (const secret of resolvedSecrets) {
+          if (secret && String(secret).length >= 4 && out.includes(secret)) {
+            out = out.replaceAll(secret, '[REDACTED_CREDENTIAL]');
+          }
+        }
+        result.output = out;
+      }
+      return result;
+    };
+
+    const runInternal = async () => {
+      // 1. Non-LLM runtimes: shell, Node.js, Python, HTTP, SSH, Docker (#4 #5 #7 #8 #9)
+      const runtime = normalizeTaskType(effectiveTask.type);
+      if (EXTERNAL_RUNTIMES.includes(runtime) || effectiveTask.mode === 'no-llm') {
+        return this._runExternal(effectiveTask, runtime === 'llm' ? 'script' : runtime, signal, options);
+      }
+
+      // 2. Agent session, when the harness exposes one
+      if (this.ctx && this.ctx.agents && typeof this.ctx.agents.create === 'function') {
+        return this._runAgentSession(effectiveTask, runtime, signal, options);
+      }
+
+      // 3. Legacy session service
+      if (this.ctx && this.ctx.session && typeof this.ctx.session.create === 'function') {
+        return this._runLegacySession(effectiveTask, options);
+      }
+
+      // 4. Nothing to run through: report the prompt as triggered
+      return this._runBare(effectiveTask, options);
+    };
+
+    try {
+      const outcome = await runInternal();
+      return maskSecrets(outcome);
+    } catch (err) {
+      if (resolvedSecrets.length > 0 && err && err.message) {
+        for (const secret of resolvedSecrets) {
+          if (secret && String(secret).length >= 4 && err.message.includes(secret)) {
+            err.message = err.message.replaceAll(secret, '[REDACTED_CREDENTIAL]');
+          }
+        }
+      }
+      throw err;
+    }
+  }
+
+  // Legacy dispatch replaced above; original runner helpers remain unchanged below:
+  async _runOriginalDispatch(task, signal, options = {}) {
     const runtime = normalizeTaskType(task.type);
     if (EXTERNAL_RUNTIMES.includes(runtime) || task.mode === 'no-llm') {
       return this._runExternal(task, runtime === 'llm' ? 'script' : runtime, signal, options);

package/lib/scheduler-lifecycle.js

@@ -92,6 +92,9 @@ export function pauseTask(scheduler, taskId, reason = null) {
     clearTimeout(scheduler.timers.get(taskId));
     scheduler.timers.delete(taskId);
   }
+  if (scheduler.watcherManager) {
+    scheduler.watcherManager.unwatchTask(taskId);
+  }
   const running = scheduler.running.get(taskId);
   if (running) {
     bestEffort('abort-paused-task', () => running.controller.abort(new Error('Task paused')), scheduler.logger);
@@ -115,6 +118,9 @@ export function removeTask(scheduler, taskId) {
     clearTimeout(scheduler.timers.get(taskId));
     scheduler.timers.delete(taskId);
   }
+  if (scheduler.watcherManager) {
+    scheduler.watcherManager.unwatchTask(taskId);
+  }
   const running = scheduler.running.get(taskId);
   if (running) {
     bestEffort('abort-deleted-task', () => running.controller.abort(new Error('Task deleted')), scheduler.logger);

package/lib/scheduler.js

@@ -1,6 +1,7 @@
 import { logger } from './logger.js';
 import { bestEffort } from './best-effort.js';
 import { Cron } from 'croner';
+import { FileSystemWatcherManager } from './watcher.js';
 
 const MAX_TIMEOUT_MS = 2147483647; // 2^31 - 1 ms (~24.85 days)
 import {
@@ -51,6 +52,7 @@ export {
   removeTask,
   resumeTask,
   toggleTask,
+  FileSystemWatcherManager,
 };
 
 function pad(v) {
@@ -320,6 +322,7 @@ export class TaskScheduler {
     this.queue = [];
     this.groupLimits = opts.groupLimits instanceof Map ? opts.groupLimits : new Map(Object.entries(opts.groupLimits || {}));
     this.heartbeatTimer = null;
+    this.watcherManager = new FileSystemWatcherManager(this);
     this.logger = opts.logger || null;
     this.isStopped = false;
     this.generation = 0;
@@ -416,12 +419,18 @@ export class TaskScheduler {
       this.scheduleTask(task);
     }
     this.startHeartbeatWatcher();
+    if (this.watcherManager) {
+      this.watcherManager.syncAll(tasks);
+    }
   }
 
   stopAll() {
     this.isStopped = true;
     this.generation = (this.generation || 0) + 1;
     this.stopHeartbeatWatcher();
+    if (this.watcherManager) {
+      this.watcherManager.stopAll();
+    }
 
     // Clear concurrency queue (#217)
     this.queue = [];
@@ -452,6 +461,9 @@ export class TaskScheduler {
   }
 
   clearScheduled(taskId) {
+    if (this.watcherManager) {
+      this.watcherManager.unwatchTask(taskId);
+    }
     if (this.jobs.has(taskId)) {
       this.jobs.get(taskId).stop();
       this.jobs.delete(taskId);
@@ -516,6 +528,9 @@ export class TaskScheduler {
     this.clearScheduled(task.id);
     if (task.status !== 'active') return;
     this.clearRetryTimer(task.id);
+    if (this.watcherManager) {
+      this.watcherManager.watchTask(task);
+    }
 
     try {
       const parsed = parseScheduleExpression(task.schedule);

package/lib/secrets.js

@@ -120,3 +120,117 @@ export async function resolveTelegramSecrets(ctx, settings = {}) {
   out.chatId = String(settings.chatId || '').trim();
   return out;
 }
+
+
+// --- Dynamic credential resolution (#335) ---
+export const CREDENTIAL_URI_REGEX = /^credential:\/\/(?:([a-zA-Z0-9_-]+)\/)?([a-zA-Z0-9_.-]+)$/;
+export const CREDENTIAL_URI_GLOBAL_REGEX = /credential:\/\/(?:[a-zA-Z0-9_-]+\/)?[a-zA-Z0-9_.-]+/g;
+
+/** Check if a string is a credential:// reference URI. */
+export function isCredentialUri(value) {
+  return typeof value === 'string' && CREDENTIAL_URI_REGEX.test(value.trim());
+}
+
+/** Parse a credential://[domain/]<key> URI into domain and key components. */
+export function parseCredentialUri(value) {
+  const match = String(value || '').trim().match(CREDENTIAL_URI_REGEX);
+  if (!match) return null;
+  return {
+    domain: match[1] || null,
+    key: match[2],
+  };
+}
+
+/**
+ * Resolve a single credential:// URI using harness credentials service or environment.
+ * If not resolvable, returns the original URI.
+ */
+export async function resolveCredentialReference(uri, ctx) {
+  if (typeof uri !== 'string') return uri;
+  const parsed = parseCredentialUri(uri);
+  if (!parsed) return uri;
+
+  try {
+    const creds = (ctx && typeof ctx.get === 'function' ? ctx.get('credentials') : null)
+      || (ctx && ctx.credentials);
+    if (creds && typeof creds.resolve === 'function') {
+      const hit = await creds.resolve(parsed.domain ? { domain: parsed.domain, name: parsed.key } : parsed.key);
+      if (hit && hit.value) return String(hit.value);
+    }
+  } catch {
+    // credentials service unavailable
+  }
+
+  // Fallback: resolve by key name
+  const fallback = await resolveCredentialValue(ctx, parsed.key);
+  if (fallback) return fallback;
+
+  // Fallback: check environment variable with DOMAIN_KEY
+  if (parsed.domain) {
+    const prefixedEnv = process.env[`${parsed.domain.toUpperCase()}_${parsed.key.toUpperCase()}`];
+    if (prefixedEnv) return String(prefixedEnv);
+  }
+
+  return uri;
+}
+
+/**
+ * Replace all credential://... references in a string with resolved secret values.
+ * Returns { text: string, resolvedSecrets: string[] }.
+ */
+export async function resolveDynamicCredentialsInText(text, ctx) {
+  if (typeof text !== 'string' || !text.includes('credential://')) {
+    return { text, resolvedSecrets: [] };
+  }
+
+  const matches = text.match(CREDENTIAL_URI_GLOBAL_REGEX);
+  if (!matches || !matches.length) {
+    return { text, resolvedSecrets: [] };
+  }
+
+  let result = text;
+  const resolvedSecrets = [];
+
+  for (const match of matches) {
+    const resolved = await resolveCredentialReference(match, ctx);
+    if (resolved && resolved !== match) {
+      result = result.replaceAll(match, resolved);
+      resolvedSecrets.push(resolved);
+    }
+  }
+
+  return { text: result, resolvedSecrets };
+}
+
+/**
+ * Recursively resolve credential://... references in strings, arrays, or objects.
+ * Returns { data: any, resolvedSecrets: string[] }.
+ */
+export async function resolveDynamicCredentialsInObject(obj, ctx) {
+  if (obj === null || obj === undefined) return { data: obj, resolvedSecrets: [] };
+  if (typeof obj === 'string') {
+    const textRes = await resolveDynamicCredentialsInText(obj, ctx);
+    return { data: textRes.text, resolvedSecrets: textRes.resolvedSecrets };
+  }
+  if (Array.isArray(obj)) {
+    const outArr = [];
+    const allSecrets = [];
+    for (const item of obj) {
+      const res = await resolveDynamicCredentialsInObject(item, ctx);
+      outArr.push(res.data);
+      allSecrets.push(...res.resolvedSecrets);
+    }
+    return { data: outArr, resolvedSecrets: allSecrets };
+  }
+  if (typeof obj === 'object') {
+    const outObj = {};
+    const allSecrets = [];
+    for (const [k, v] of Object.entries(obj)) {
+      const res = await resolveDynamicCredentialsInObject(v, ctx);
+      outObj[k] = res.data;
+      allSecrets.push(...res.resolvedSecrets);
+    }
+    return { data: outObj, resolvedSecrets: allSecrets };
+  }
+  return { data: obj, resolvedSecrets: [] };
+}

package/lib/settings.js

@@ -47,6 +47,8 @@ export const Config = z.object({
   giteaLabels: z.any().default([]).description('Gitea label names or IDs for alert issues').volatile(),
   giteaLabelIds: z.any().default({}).description('Mapping of label name to integer ID for Gitea issues').volatile(),
   prReviewerEnabled: z.boolean().default(false).description('Enable automated PR Reviewer scheduled agent (#33)').volatile(),
+  // --- Dynamic credentials resolution (#335) ---
+  enableDynamicCredentials: z.boolean().default(false).description('Enable dynamic credential://... reference resolution at runtime (#335)').volatile(),
   // --- Global Budgets (#320) ---
   globalDailyCostLimitUsd: z.number().default(0).description('Global daily expenditure limit in USD across all tasks (0 = unlimited)').volatile(),
   providerHourlyRunLimits: z.object({}).default({}).description('Max runs per hour keyed by provider').volatile(),
@@ -85,7 +87,7 @@ export const SETTINGS_SYNC_KEYS = [
   'pushplusTokenRef',
   'pushplusUrl',
   'ttsBaseUrl',
-  'giteaBaseUrl', 'giteaRepo', 'giteaTokenRef', 'giteaLabels', 'giteaLabelIds', 'prReviewerEnabled',
+  'giteaBaseUrl', 'giteaRepo', 'giteaTokenRef', 'giteaLabels', 'giteaLabelIds', 'prReviewerEnabled', 'enableDynamicCredentials',
   'apiToken',
   'globalDailyCostLimitUsd', 'providerHourlyRunLimits', 'modelHourlyRunLimits',
 ];

package/lib/task-create.js

@@ -5,6 +5,22 @@ import { parseScheduleExpression } from './scheduler.js';
 import { CHANNEL_IDS } from './channels.js';
 import { redactTaskSecrets } from './http-utils.js';
 
+export function sanitizeFileWatch(fw) {
+  if (!fw || typeof fw !== 'object') return undefined;
+  const p = String(fw.path || '').trim();
+  if (!p) return undefined;
+  return {
+    enabled: Boolean(fw.enabled !== false),
+    path: p,
+    pattern: fw.pattern ? String(fw.pattern).trim() : '*',
+    events: Array.isArray(fw.events) && fw.events.length > 0
+      ? fw.events.map(String).filter((e) => ['create', 'modify', 'delete'].includes(e))
+      : ['create', 'modify'],
+    debounceMs: Math.max(50, Number(fw.debounceMs) || 500),
+    recursive: Boolean(fw.recursive),
+  };
+}
+
 export function executeCreateTask(store, scheduler, args) {
   const taskType = normalizeTaskType(args.type);
   const typeError = validateTaskType(taskType, args);
@@ -75,6 +91,7 @@ export function executeCreateTask(store, scheduler, args) {
     tokenLimit: Number(args.tokenLimit) > 0 ? Number(args.tokenLimit) : undefined,
     validators: Array.isArray(args.validators) ? sanitizeValidators(args.validators) : undefined,
     requireApproval: Boolean(args.requireApproval),
+    fileWatch: args.fileWatch && typeof args.fileWatch === 'object' ? sanitizeFileWatch(args.fileWatch) : undefined,
   };
   // Issue #310 / GH #5: strip any undefined properties before store.set()
   for (const k of Object.keys(taskData)) {

package/lib/task-patch.js

@@ -1,4 +1,5 @@
 import { sanitizeValidators } from './validators.js';
+import { sanitizeFileWatch } from './task-create.js';
 /**
  * Partial task updates, shared by the HTTP PATCH route and the cron tool (action: 'update')
  * tool (#49).
@@ -90,6 +91,9 @@ export function buildTaskPatch(current, body) {
   if (patch.requireApproval !== undefined) {
     patch.requireApproval = Boolean(patch.requireApproval);
   }
+  if (patch.fileWatch !== undefined) {
+    patch.fileWatch = patch.fileWatch && typeof patch.fileWatch === 'object' ? sanitizeFileWatch(patch.fileWatch) : null;
+  }
   if (patch.validators !== undefined) {
     patch.validators = Array.isArray(patch.validators) ? sanitizeValidators(patch.validators) : [];
   }

package/lib/task-transfer.js

@@ -76,6 +76,7 @@ export const PATCHABLE_TASK_FIELDS = [
   'pausedReason',
   'validators',
   'requireApproval',
+  'fileWatch',
 ];
 
 /** Fields a duplicate inherits; anything else is runtime state, not config. */

package/lib/watcher.js

@@ -0,0 +1,249 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { logger } from './logger.js';
+import { bestEffort } from './best-effort.js';
+
+const DISALLOWED_ROOTS = [
+  '/',
+  '/proc',
+  '/sys',
+  '/dev',
+  '/etc',
+  '/boot',
+  '/run',
+  '/var/run',
+  'c:\\',
+  'c:\\windows',
+  'c:\\windows\\system32',
+  'c:\\program files',
+  'c:\\program files (x86)',
+];
+
+/**
+ * FileSystemWatcherManager handles fs.watch instances for tasks configured with fileWatch (#327).
+ * Provides safe path validation, debounce event filtering, pattern glob matching, and task triggers.
+ */
+export class FileSystemWatcherManager {
+  constructor(scheduler) {
+    this.scheduler = scheduler;
+    this.watchers = new Map(); // taskId -> { watcher, config, dir }
+    this.debounceTimers = new Map(); // `${taskId}:${filename}` -> timer
+    this.knownFiles = new Map(); // taskId -> Set(filename)
+  }
+
+  isSafePath(targetPath) {
+    if (!targetPath || typeof targetPath !== 'string') {
+      return { safe: false, error: 'Path must be a non-empty string' };
+    }
+    const resolved = path.resolve(targetPath.trim());
+    const lower = resolved.toLowerCase();
+
+    for (const root of DISALLOWED_ROOTS) {
+      if (lower === root || lower === root.replace(/\\/g, '/')) {
+        return { safe: false, error: `Watched path "${resolved}" is a disallowed system root directory` };
+      }
+    }
+
+    if (resolved === path.parse(resolved).root) {
+      return { safe: false, error: `Watched path "${resolved}" is a filesystem root` };
+    }
+
+    return { safe: true, resolved };
+  }
+
+  matchPattern(filename, pattern) {
+    if (!pattern || pattern.trim() === '' || pattern === '*') return true;
+    const parts = pattern.split(',').map((p) => p.trim()).filter(Boolean);
+    if (!parts.length) return true;
+
+    return parts.some((p) => {
+      const regexStr = '^' + p.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.') + '$';
+      try {
+        return new RegExp(regexStr, 'i').test(filename);
+      } catch {
+        return false;
+      }
+    });
+  }
+
+  watchTask(task) {
+    if (!task || !task.id) return;
+    const fw = task.fileWatch;
+
+    if (!fw || !fw.enabled || task.status !== 'active') {
+      this.unwatchTask(task.id);
+      return;
+    }
+
+    const check = this.isSafePath(fw.path);
+    if (!check.safe) {
+      logger.warn(`[dsh-cron] Unsafe fileWatch path for task "${task.title}" (${task.id}): ${check.error}`);
+      this.unwatchTask(task.id);
+      return;
+    }
+
+    const watchDir = check.resolved;
+    if (!fs.existsSync(watchDir)) {
+      logger.warn(`[dsh-cron] Watched directory does not exist for task "${task.title}" (${task.id}): ${watchDir}`);
+      this.unwatchTask(task.id);
+      return;
+    }
+
+    const current = this.watchers.get(task.id);
+    const configSig = JSON.stringify({
+      dir: watchDir,
+      pattern: fw.pattern || '*',
+      events: fw.events || ['create', 'modify'],
+      debounceMs: fw.debounceMs || 500,
+      recursive: Boolean(fw.recursive),
+    });
+
+    if (current && current.sig === configSig) {
+      return; // Already watching with exact configuration
+    }
+
+    this.unwatchTask(task.id);
+
+    // Initial snapshot of known files in directory
+    const known = new Set();
+    try {
+      const entries = fs.readdirSync(watchDir);
+      for (const entry of entries) {
+        known.add(entry);
+      }
+    } catch {
+      // ignore readdir errors
+    }
+    this.knownFiles.set(task.id, known);
+
+    try {
+      const watcher = fs.watch(watchDir, { recursive: Boolean(fw.recursive) }, (rawEvent, filename) => {
+        if (!filename) return;
+        // Ignore dotfiles / temp files unless pattern specifically targets them
+        if (filename.startsWith('.') && (!fw.pattern || !fw.pattern.startsWith('.'))) return;
+
+        const debounceMs = Math.max(50, Number(fw.debounceMs) || 500);
+        const timerKey = `${task.id}:${filename}`;
+
+        if (this.debounceTimers.has(timerKey)) {
+          clearTimeout(this.debounceTimers.get(timerKey));
+        }
+
+        const timer = setTimeout(() => {
+          this.debounceTimers.delete(timerKey);
+          this._handleEvent(task, watchDir, filename, rawEvent);
+        }, debounceMs);
+
+        if (timer.unref) timer.unref();
+        this.debounceTimers.set(timerKey, timer);
+      });
+
+      watcher.on('error', (err) => {
+        logger.error(`[dsh-cron] Watcher error for task "${task.title}" (${task.id}): ${err.message}`);
+      });
+
+      this.watchers.set(task.id, { watcher, sig: configSig, dir: watchDir });
+      logger.info(`[dsh-cron] File watcher active on "${watchDir}" for task "${task.title}" (${task.id})`);
+    } catch (err) {
+      logger.error(`[dsh-cron] Failed to start file watcher for task "${task.title}" (${task.id}): ${err.message}`);
+    }
+  }
+
+  _handleEvent(task, watchDir, filename, rawEvent) {
+    if (!this.scheduler || this.scheduler.isStopped) return;
+    const fw = task.fileWatch || {};
+    if (!fw.enabled) return;
+
+    if (!this.matchPattern(filename, fw.pattern)) {
+      return;
+    }
+
+    const fullFilePath = path.join(watchDir, filename);
+    const exists = fs.existsSync(fullFilePath);
+    let event = 'modify';
+    let fileSize = 0;
+
+    const taskKnown = this.knownFiles.get(task.id) || new Set();
+
+    if (!exists) {
+      event = 'delete';
+      fileSize = 0;
+      taskKnown.delete(filename);
+    } else {
+      try {
+        const stat = fs.statSync(fullFilePath);
+        if (stat.isDirectory()) return; // skip directories
+        fileSize = stat.size;
+        if (taskKnown.has(filename)) {
+          event = 'modify';
+        } else {
+          event = 'create';
+          taskKnown.add(filename);
+        }
+      } catch {
+        return; // Stat failed (e.g. temporary file disappeared)
+      }
+    }
+
+    const allowedEvents = Array.isArray(fw.events) && fw.events.length > 0
+      ? fw.events
+      : ['create', 'modify'];
+
+    if (!allowedEvents.includes(event)) {
+      return;
+    }
+
+    logger.info(`[dsh-cron] fileWatch triggered: "${event}" on "${filename}" for task "${task.title}" (${task.id})`);
+    this.scheduler.runTask(task.id, {
+      filePath: fullFilePath,
+      fileName: filename,
+      fileSize,
+      fileEvent: event,
+      trigger: 'fileWatch',
+    }).catch((err) => {
+      logger.error(`[dsh-cron] File watcher triggered execution error for task ${task.id}: ${err.message}`);
+    });
+  }
+
+  unwatchTask(taskId) {
+    const entry = this.watchers.get(taskId);
+    if (entry) {
+      bestEffort('watcher-close', () => entry.watcher.close());
+      this.watchers.delete(taskId);
+    }
+    this.knownFiles.delete(taskId);
+    for (const [key, timer] of this.debounceTimers.entries()) {
+      if (key.startsWith(`${taskId}:`)) {
+        clearTimeout(timer);
+        this.debounceTimers.delete(key);
+      }
+    }
+  }
+
+  stopAll() {
+    for (const [taskId] of this.watchers.entries()) {
+      this.unwatchTask(taskId);
+    }
+    this.watchers.clear();
+    for (const [, timer] of this.debounceTimers.entries()) {
+      clearTimeout(timer);
+    }
+    this.debounceTimers.clear();
+    this.knownFiles.clear();
+  }
+
+  syncAll(tasks = []) {
+    const activeTaskIds = new Set();
+    for (const task of tasks) {
+      if (task && task.id && task.status === 'active' && task.fileWatch?.enabled) {
+        activeTaskIds.add(task.id);
+        this.watchTask(task);
+      }
+    }
+    for (const [taskId] of this.watchers.entries()) {
+      if (!activeTaskIds.has(taskId)) {
+        this.unwatchTask(taskId);
+      }
+    }
+  }
+}

package/package.json

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