@goodandready/dsh-cron 0.2.5 → 0.2.7

package/lib/scheduler.js

@@ -1,4 +1,18 @@
 import { Cron } from 'croner';
+import { applySilentRule } from './silent-rule.js';
+import { inspectFailure } from './failure-inspector.js';
+
+/** Task types that talk to a model and can therefore use a fallback model. */
+export const AGENT_TASK_TYPES = ['llm', 'skill', 'workflow'];
+
+/** Sum two usage records, so a fallback attempt is not lost in accounting. */
+export function addUsage(a, b) {
+  return {
+    inputTokens: (a?.inputTokens || 0) + (b?.inputTokens || 0),
+    outputTokens: (a?.outputTokens || 0) + (b?.outputTokens || 0),
+    cacheReadTokens: (a?.cacheReadTokens || 0) + (b?.cacheReadTokens || 0),
+  };
+}
 
 function pad(v) {
   return String(v).padStart(2, '0');
@@ -22,82 +36,78 @@ export function describeCron(cronPattern) {
   return cronPattern;
 }
 
-export function parseScheduleExpression(input) {
-  const str = String(input || '').trim();
-  if (!str) throw new Error('Schedule expression must not be empty');
-
-  // 1. One-shot ISO 8601 timestamp or explicit "at: <ISO/datetime>"
+/** One-shot from an ISO timestamp or an explicit "at:" prefix, else null. */
+function parseAtExpression(str) {
   const atPrefixMatch = str.match(/^(?:at:\s*|at\s+)(.+)$/i);
   const candidateIso = atPrefixMatch ? atPrefixMatch[1].trim() : str;
   const parsedDate = new Date(candidateIso);
-  if (!isNaN(parsedDate.getTime()) && (candidateIso.includes('-') || candidateIso.includes('T') || atPrefixMatch)) {
-    const targetMs = parsedDate.getTime();
-    return {
-      cronPattern: null,
-      isOneShot: true,
-      targetTimestamp: targetMs,
-      humanText: `One-shot at ${parsedDate.toISOString()}`,
-      nextRun: targetMs
-    };
+  if (isNaN(parsedDate.getTime()) || !(candidateIso.includes('-') || candidateIso.includes('T') || atPrefixMatch)) {
+    return null;
   }
+  const targetMs = parsedDate.getTime();
+  return {
+    cronPattern: null,
+    isOneShot: true,
+    targetTimestamp: targetMs,
+    humanText: `One-shot at ${parsedDate.toISOString()}`,
+    nextRun: targetMs
+  };
+}
 
-  // 2. Relative one-shot: "in 20m", "in 2h", "in 30s", "in 1d", "через 15 минут"
-  //    Russian keywords are accepted input aliases, not display strings.
-  const inRelMatch = str.match(/^(?:in\s+|через\s+)(\d+)\s*(s|sec|seconds?|m|min|minutes?|h|hr|hours?|d|days?|мин|минут|часа?|часов)?$/i);
-  if (inRelMatch) {
-    const num = parseInt(inRelMatch[1], 10);
-    const unit = (inRelMatch[2] || 'm').toLowerCase();
-    let delayMs = num * 60 * 1000;
-    let unitText = `${num} min`;
-    if (unit.startsWith('s')) {
-      delayMs = num * 1000;
-      unitText = `${num} sec`;
-    } else if (unit.startsWith('h') || unit.startsWith('час')) {
-      delayMs = num * 3600 * 1000;
-      unitText = `${num} h`;
-    } else if (unit.startsWith('d')) {
-      delayMs = num * 86400 * 1000;
-      unitText = `${num} d`;
-    }
-    const targetMs = Date.now() + delayMs;
-    return {
-      cronPattern: null,
-      isOneShot: true,
-      targetTimestamp: targetMs,
-      humanText: `One-shot in ${unitText} (at ${new Date(targetMs).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })})`,
-      nextRun: targetMs
-    };
+/**
+ * Relative one-shot: "in 20m", "in 2h", "in 30s", "in 1d" and the accepted
+ * Russian input aliases ("через 15 минут").
+ */
+function parseRelativeOneShot(str) {
+  const match = str.match(/^(?:in\s+|через\s+)(\d+)\s*(s|sec|seconds?|m|min|minutes?|h|hr|hours?|d|days?|мин|минут|часа?|часов)?$/i);
+  if (!match) return null;
+  const num = parseInt(match[1], 10);
+  const unit = (match[2] || 'm').toLowerCase();
+  let delayMs = num * 60 * 1000;
+  let unitText = `${num} min`;
+  if (unit.startsWith('s')) {
+    delayMs = num * 1000;
+    unitText = `${num} sec`;
+  } else if (unit.startsWith('h') || unit.startsWith('час')) {
+    delayMs = num * 3600 * 1000;
+    unitText = `${num} h`;
+  } else if (unit.startsWith('d')) {
+    delayMs = num * 86400 * 1000;
+    unitText = `${num} d`;
   }
+  const targetMs = Date.now() + delayMs;
+  return {
+    cronPattern: null,
+    isOneShot: true,
+    targetTimestamp: targetMs,
+    humanText: `One-shot in ${unitText} (at ${new Date(targetMs).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })})`,
+    nextRun: targetMs
+  };
+}
 
-  // 3. Repeating Interval: "every 5m", "every 2h", "every 1d"
-  const intervalMatch = str.match(/^every\s+(\d+)\s*(m|min|minute|minutes|h|hr|hour|hours|d|day|days)?$/i);
-  if (intervalMatch) {
-    const num = parseInt(intervalMatch[1], 10);
-    const unit = (intervalMatch[2] || 'm').toLowerCase();
-    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 (unit.startsWith('d')) {
-      return {
-        cronPattern: `0 0 */${num} * *`,
-        humanText: `Every ${num} days`,
-        isInterval: true,
-      };
-    }
+/** Repeating interval: "every 5m", "every 2h", "every 1d". */
+function parseIntervalExpression(str) {
+  const match = str.match(/^every\s+(\d+)\s*(m|min|minute|minutes|h|hr|hour|hours|d|day|days)?$/i);
+  if (!match) return null;
+  const num = parseInt(match[1], 10);
+  const unit = (match[2] || 'm').toLowerCase();
+  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 (unit.startsWith('d')) {
+    return { cronPattern: `0 0 */${num} * *`, humanText: `Every ${num} days`, isInterval: true };
   }
+  return null;
+}
 
-  // 4. Standard @-shorthands (#15)
+/**
+ * @-shorthands (#15) and the friendly aliases, including the Russian input
+ * aliases. Russian keywords are accepted input, not display strings.
+ */
+function parseAliasExpression(str) {
   const lower = str.toLowerCase();
   if (lower === '@hourly') return { cronPattern: '0 * * * *', humanText: 'Every hour' };
   if (lower === '@daily' || lower === '@midnight') return { cronPattern: '0 0 * * *', humanText: 'Every day at 00:00' };
@@ -106,10 +116,9 @@ export function parseScheduleExpression(input) {
   if (lower === '@yearly' || lower === '@annually') return { cronPattern: '0 0 1 1 *', humanText: 'Every year on Jan 1 at 00:00' };
   const everyAlias = str.match(/^@every\s+(\d+)\s*(sec|seconds?|m|min|minutes?|h|hr|hours?|d|days?)$/i);
   if (everyAlias) {
-    return parseScheduleExpression(`every ${everyAlias[1]} ${everyAlias[2]}`);
+    // "@every N unit" is another spelling of the interval branch.
+    return parseIntervalExpression(`every ${everyAlias[1]} ${everyAlias[2]}`);
   }
-
-  // 5. Friendly recurring aliases (English plus accepted Russian input aliases)
   if (lower === 'daily' || lower === 'каждый день') {
     return { cronPattern: '0 9 * * *', humanText: 'Every day at 09:00' };
   }
@@ -119,8 +128,11 @@ export function parseScheduleExpression(input) {
   if (lower === 'hourly' || lower === 'каждый час') {
     return { cronPattern: '0 * * * *', humanText: 'Every hour' };
   }
+  return null;
+}
 
-  // 5. Standard 5-field cron expression
+/** Validate a 5-field cron expression; the only branch that throws. */
+function parseCronExpression(str) {
   try {
     const testJob = new Cron(str);
     const next = testJob.nextRun();
@@ -134,6 +146,22 @@ export function parseScheduleExpression(input) {
   }
 }
 
+/**
+ * Turn a typed schedule into a cron pattern or a one-shot target. The branch
+ * order is the contract: a timestamp, a relative one-shot, an interval and an
+ * alias are all more specific than a raw cron expression.
+ */
+export function parseScheduleExpression(input) {
+  const str = String(input || '').trim();
+  if (!str) throw new Error('Schedule expression must not be empty');
+
+  return parseAtExpression(str)
+    || parseRelativeOneShot(str)
+    || parseIntervalExpression(str)
+    || parseAliasExpression(str)
+    || parseCronExpression(str);
+}
+
 export class TaskScheduler {
   constructor(store, executeFn, options = {}) {
     this.store = store;
@@ -146,6 +174,7 @@ export class TaskScheduler {
     this.timers = new Map(); // taskId -> setTimeout handle (for one-shot tasks)
     this.retryTimers = new Map(); // taskId -> setTimeout handle (for #18 retries)
     this.running = new Map(); // taskId -> { controller, startedAt, queueCount }
+    this.runCounters = {}; // status -> finished runs since start (#53, /dsh-cron/metrics)
   }
 
   isRunning(taskId) {
@@ -180,6 +209,7 @@ export class TaskScheduler {
         const missedAt = task.nextRunAt;
         const policy = task.misfirePolicy || 'skip'; // #12: skip | runOnce | catchUpAll
         console.warn(`[dsh-cron] Task "${task.title}" (${task.id}) missed scheduled run at ${new Date(missedAt).toISOString()} (misfire: ${policy})`);
+        this.countRun('missed');
         this.store.recordRun(task.id, {
           at: missedAt,
           status: 'missed',
@@ -239,102 +269,92 @@ export class TaskScheduler {
     this.running.clear();
   }
 
-  scheduleTask(task) {
-    // Clear any existing job or timer for this task
-    if (this.jobs.has(task.id)) {
-      this.jobs.get(task.id).stop();
-      this.jobs.delete(task.id);
+  /** Drop an armed job or one-shot timer before re-scheduling a task. */
+  clearScheduled(taskId) {
+    if (this.jobs.has(taskId)) {
+      this.jobs.get(taskId).stop();
+      this.jobs.delete(taskId);
+    }
+    if (this.timers.has(taskId)) {
+      clearTimeout(this.timers.get(taskId));
+      this.timers.delete(taskId);
     }
-    if (this.timers.has(task.id)) {
-      clearTimeout(this.timers.get(task.id));
+  }
+
+  /** Arm a one-shot task; a target already in the past fires immediately. */
+  scheduleOneShot(task, parsed) {
+    task.oneShot = true;
+    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) => {
+        console.error(`[dsh-cron] one-shot run of task ${task.id} failed:`, (err && err.message) || err);
+      });
+    }, delay);
+    this.timers.set(task.id, timer);
+  }
+
+  /** Arm a recurring cron job and persist the next run timestamp. */
+  scheduleCron(task, parsed) {
+    const timezone = task.timezone || this.defaultTimezone || undefined;
+    const job = new Cron(parsed.cronPattern, {
+      protect: true,
+      catch: (err) => console.error(`[dsh-cron] scheduled run of "${task.title}" (${task.id}) failed:`, (err && err.message) || err),
+      ...(timezone ? { timezone } : {}),
+    }, async () => {
+      await this.runTask(task.id);
+    });
+
+    this.jobs.set(task.id, job);
+    const next = job.nextRun();
+    if (next) {
+      task.nextRunAt = next.getTime();
+      this.store.set(task);
     }
+  }
 
+  scheduleTask(task) {
+    this.clearScheduled(task.id);
     if (task.status !== 'active') return;
     this.clearRetryTimer(task.id);
 
     try {
       const parsed = parseScheduleExpression(task.schedule);
-      const timezone = task.timezone || this.defaultTimezone || undefined;
-
-      // Handle One-shot task
       if (parsed.isOneShot) {
-        task.oneShot = true;
-        const now = Date.now();
-        const delay = Math.max(0, parsed.targetTimestamp - now);
-        task.nextRunAt = parsed.targetTimestamp;
-        this.store.set(task);
-
-        // If target is in the past, or when delay triggers:
-        const timer = setTimeout(() => {
-          this.timers.delete(task.id);
-          this.runTask(task.id).catch((err) => {
-            console.error(`[dsh-cron] one-shot run of task ${task.id} failed:`, (err && err.message) || err);
-          });
-        }, delay);
-
-        this.timers.set(task.id, timer);
+        this.scheduleOneShot(task, parsed);
         return;
       }
-
-      // Handle Recurring Cron job
-      const job = new Cron(parsed.cronPattern, {
-        protect: true,
-        catch: (err) => console.error(`[dsh-cron] scheduled run of "${task.title}" (${task.id}) failed:`, (err && err.message) || err),
-        ...(timezone ? { timezone } : {}),
-      }, async () => {
-        await this.runTask(task.id);
-      });
-
-      this.jobs.set(task.id, job);
-      const next = job.nextRun();
-      if (next) {
-        task.nextRunAt = next.getTime();
-        this.store.set(task);
-      }
+      this.scheduleCron(task, parsed);
     } catch (err) {
       console.error(`[dsh-cron] failed to schedule task ${task.id}:`, err.message);
     }
   }
 
-  async runTask(taskId) {
-    const task = this.store.get(taskId);
-    if (!task) return;
-
+  /**
+   * Pre-flight guards for a run: the global concurrency throttle (#52) and the
+   * per-task overlap policy. Returns the run token to continue with, or null
+   * when this tick must not execute (the reason is already recorded).
+   */
+  beginRun(task, taskId) {
     // Global concurrency throttle (#52): a run that would exceed the limit is
     // skipped and recorded; already-running tasks are never throttled against
     // themselves.
     if (!this.running.has(taskId) && this.maxConcurrent > 0 && this.running.size >= this.maxConcurrent) {
       console.log(`[dsh-cron] Task "${task.title}" (${taskId}) skipped: concurrency limit (${this.maxConcurrent})`);
-      this.store.recordRun(taskId, {
-        at: Date.now(),
-        status: 'skipped',
-        durationMs: 0,
-        output: `Skipped: concurrency limit reached (${this.maxConcurrent} parallel runs)`,
-        error: null,
-        usage: { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0 },
-        costUsd: 0,
-      });
-      return;
+      this.recordSkipped(taskId, `Skipped: concurrency limit reached (${this.maxConcurrent} parallel runs)`);
+      return null;
     }
 
     const overlapPolicy = task.overlapPolicy || 'skip';
-
-    // Check overlap with currently running task
     const active = this.running.get(taskId);
     if (active) {
       if (overlapPolicy === 'skip') {
         console.log(`[dsh-cron] Task "${task.title}" (${taskId}) is already running, skipping run (overlapPolicy: skip)`);
-        this.store.recordRun(taskId, {
-          at: Date.now(),
-          status: 'skipped',
-          durationMs: 0,
-          output: 'Skipped: the previous run is still in progress (overlapPolicy: skip)',
-          error: null,
-          usage: { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0 },
-          costUsd: 0,
-        });
-        return;
+        this.recordSkipped(taskId, 'Skipped: the previous run is still in progress (overlapPolicy: skip)');
+        return null;
       }
       if (overlapPolicy === 'replace') {
         console.log(`[dsh-cron] Task "${task.title}" (${taskId}) is already running, canceling current run (overlapPolicy: replace)`);
@@ -343,73 +363,233 @@ export class TaskScheduler {
       if (overlapPolicy === 'queue') {
         console.log(`[dsh-cron] Task "${task.title}" (${taskId}) is already running, queueing next run (overlapPolicy: queue)`);
         active.queueCount = (active.queueCount || 0) + 1;
-        return;
+        return null;
       }
     }
 
     const controller = new AbortController();
-    const currentRun = {
-      controller,
-      startedAt: Date.now(),
-      queueCount: 0,
-    };
+    const currentRun = { controller, startedAt: Date.now(), queueCount: 0 };
     this.running.set(taskId, currentRun);
+    return currentRun;
+  }
 
-    const start = Date.now();
-    let status = 'success';
-    let output = '';
-    let error = null;
-    let usage = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0 };
-    let costUsd = 0;
-    let sessionId = null;
+  /** Count a finished run for the metrics endpoint (#53). */
+  countRun(status) {
+    const key = status || 'unknown';
+    this.runCounters[key] = (this.runCounters[key] || 0) + 1;
+  }
 
+  /** Snapshot of the run counters; the caller must not mutate it. */
+  getRunCounters() {
+    return { ...this.runCounters };
+  }
+
+  /** Record a run that never started, with the reason in the history entry. */
+  recordSkipped(taskId, reason) {
+    this.countRun('skipped');
+    this.store.recordRun(taskId, {
+      at: Date.now(),
+      status: 'skipped',
+      durationMs: 0,
+      output: reason,
+      error: null,
+      usage: { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0 },
+      costUsd: 0,
+    });
+  }
+
+  /** Run the task body once and normalise whatever the executor returned. */
+  async executeOnce(task, signal) {
+    const result = {
+      status: 'success',
+      output: '',
+      error: null,
+      usage: { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0 },
+      costUsd: 0,
+      sessionId: null,
+      model: task.model || '',
+      fallback: false,
+    };
+    if (typeof this.executeFn !== 'function') return result;
     try {
-      if (typeof this.executeFn === 'function') {
-        const res = await this.executeFn(task, { signal: controller.signal });
-        if (typeof res === 'object' && res !== null) {
-          output = res.output || '';
-          usage = res.usage || usage;
-          costUsd = res.costUsd || 0;
-          sessionId = res.sessionId || null;
-        } else {
-          output = String(res || '');
-        }
-      }
-    } catch (err) {
-      error = err.message || String(err);
-      if (error.toLowerCase().includes('timed out') || error.toLowerCase().includes('timeout')) {
-        status = 'timeout';
+      const res = await this.executeFn(task, { signal });
+      if (typeof res === 'object' && res !== null) {
+        result.output = res.output || '';
+        result.usage = res.usage || result.usage;
+        result.costUsd = res.costUsd || 0;
+        result.sessionId = res.sessionId || null;
+        if (res.model) result.model = res.model;
       } else {
-        status = 'error';
-      }
-    } finally {
-      const durationMs = Date.now() - start;
-      const runInfo = {
-        at: start,
-        status,
-        durationMs,
-        output,
-        error,
-        usage,
-        costUsd,
-        sessionId,
-      };
-      try {
-        this.store.recordRun(taskId, runInfo);
-      } catch (recordErr) {
-        console.error(`[dsh-cron] failed to record the run of task ${taskId}:`, recordErr.message);
+        result.output = String(res || '');
       }
+    } catch (err) {
+      result.error = err.message || String(err);
+      const timedOut = result.error.toLowerCase().includes('timed out') || result.error.toLowerCase().includes('timeout');
+      result.status = timedOut ? 'timeout' : 'error';
+    }
+    return result;
+  }
 
-      // Clean up running map
-      const finishedRun = this.running.get(taskId);
-      if (finishedRun === currentRun) {
-        this.running.delete(taskId);
-      }
+  /**
+   * Run the task, retrying once on the configured fallback model when the
+   * primary attempt failed (#45).
+   *
+   * The point is cost: a task can default to the cheap model and still finish
+   * on the strong one when the cheap model cannot do the job. Exactly one
+   * fallback attempt is made — the ordinary retry backoff still applies
+   * afterwards — and usage and cost of BOTH attempts are summed, because both
+   * were really spent.
+   */
+  async executeWithFallback(task, signal) {
+    const primary = await this.executeOnce(task, signal);
+    if (!this.shouldUseFallback(task, primary)) return primary;
+
+    const fallbackTask = {
+      ...task,
+      provider: task.fallbackProvider || task.provider,
+      model: task.fallbackModel,
+    };
+    console.log(`[dsh-cron] task "${task.title}" failed on ${task.model || 'the default model'}, retrying once on ${task.fallbackModel}`);
+    const secondary = await this.executeOnce(fallbackTask, signal);
+    return {
+      ...secondary,
+      fallback: true,
+      usage: addUsage(primary.usage, secondary.usage),
+      costUsd: Number((primary.costUsd + secondary.costUsd).toFixed(6)),
+      primaryModel: task.model || '',
+    };
+  }
+
+  /** Only agent-mediated types use a model, and only a failed run falls back. */
+  shouldUseFallback(task, outcome) {
+    if (!task || !task.fallbackModel) return false;
+    if (!AGENT_TASK_TYPES.includes(task.type || 'llm')) return false;
+    return outcome.status === 'error' || outcome.status === 'timeout';
+  }
 
-      const queuedCount = finishedRun?.queueCount || 0;
 
-      await this.deliverNotifications(task, runInfo);
-      this.finishRun(task, taskId, status, queuedCount);
+  async runTask(taskId) {
+    const task = this.store.get(taskId);
+    if (!task) return;
+
+    const currentRun = this.beginRun(task, taskId);
+    if (currentRun === null) return;
+
+    const start = Date.now();
+    const outcome = await this.executeWithFallback(task, currentRun.controller.signal);
+    await this.completeRun(task, taskId, currentRun, outcome, start);
+  }
+
+  /**
+   * Record the run, release the run slot and hand the result to delivery and
+   * bookkeeping. Kept separate from runTask so the run flow reads in steps.
+   */
+  async completeRun(task, taskId, currentRun, outcome, start) {
+    const runInfo = {
+      at: start,
+      status: outcome.status,
+      durationMs: Date.now() - start,
+      output: outcome.output,
+      error: outcome.error,
+      usage: outcome.usage,
+      costUsd: outcome.costUsd,
+      sessionId: outcome.sessionId,
+      // #45: which model actually produced this result, and whether the run
+      // only finished thanks to the configured fallback.
+      model: outcome.model || task.model || '',
+      fallback: Boolean(outcome.fallback),
+    };
+
+    // #43/#44 decide before the run is recorded, so the single history entry
+    // already carries the diagnosis and the silence verdict.
+    const silent = await this.applyModelAssists(task, runInfo);
+
+    try {
+      this.store.recordRun(taskId, runInfo);
+    } catch (recordErr) {
+      console.error(`[dsh-cron] failed to record the run of task ${taskId}:`, recordErr.message);
+    }
+
+    // Release the slot before delivery so a long notification never blocks the
+    // next tick of this task.
+    const finishedRun = this.running.get(taskId);
+    if (finishedRun === currentRun) this.running.delete(taskId);
+    const queuedCount = finishedRun?.queueCount || 0;
+
+    if (!silent.skipped) await this.deliverNotifications(task, runInfo);
+    this.finishRun(task, taskId, outcome.status, queuedCount);
+  }
+
+  /**
+   * Run the model-assisted steps for a finished run: diagnose a failure (#43)
+   * and decide whether a successful run should stay silent (#44). Both are
+   * fail-open and write their outcome into `runInfo`.
+   */
+  async applyModelAssists(task, runInfo) {
+    const inspection = await this.inspectFailureRun(task, runInfo);
+    if (inspection.inspected) {
+      runInfo.diagnosis = inspection.diagnosis;
+      runInfo.suggestion = inspection.suggestion;
+      runInfo.confidence = inspection.confidence;
+      console.log(`[dsh-cron] task "${task.title}" failure diagnosed (${inspection.confidence}): ${inspection.diagnosis}`);
+    } else if (inspection.error && task.inspectOnFailure) {
+      console.warn(`[dsh-cron] failure inspection for "${task.title}" not applied: ${inspection.error}`);
+    }
+
+    const silent = await this.applySilentRuleToRun(task, runInfo);
+    if (silent.skipped) {
+      runInfo.silentSkip = true;
+      runInfo.silentReason = silent.reason;
+      console.log(`[dsh-cron] task "${task.title}" stayed silent by rule: ${silent.reason || 'no reason given'}`);
+    } else if (silent.verdictError) {
+      console.warn(`[dsh-cron] silent rule for "${task.title}" not applied: ${silent.verdictError}`);
+    }
+    return silent;
+  }
+
+  /** Ask the model to diagnose a failed run (#43). Never throws. */
+  async inspectFailureRun(task, runInfo) {
+    if (typeof this.askModel !== 'function') return { inspected: false, error: 'no model is available' };
+    const settings = this.readSettings();
+    try {
+      return await inspectFailure({
+        task,
+        runInfo,
+        ask: this.askModel,
+        preferredModel: String(settings.inspectorModel || ''),
+        timeoutMs: this.inspectTimeoutMs || 25000,
+      });
+    } catch (err) {
+      return { inspected: false, error: err.message };
+    }
+  }
+
+  /** Settings snapshot, or an empty object when the store has none. */
+  readSettings() {
+    try {
+      return typeof this.store.getSettings === 'function' ? this.store.getSettings() : {};
+    } catch {
+      return {};
+    }
+  }
+
+  /**
+   * Ask the silent rule whether this run should be delivered (#44).
+   * Never throws: any problem means "deliver".
+   */
+  async applySilentRuleToRun(task, runInfo) {
+    if (typeof this.askModel !== 'function') return { skipped: false, reason: '' };
+    const preferredModel = String(this.readSettings().silentRuleModel || '');
+    try {
+      return await applySilentRule({
+        task,
+        runInfo,
+        ask: this.askModel,
+        preferredModel,
+        timeoutMs: this.silentRuleTimeoutMs || 20000,
+      });
+    } catch (err) {
+      return { skipped: false, reason: '', verdictError: err.message };
     }
   }
 
@@ -449,6 +629,7 @@ export class TaskScheduler {
    * cannot reject the cron callback.
    */
   finishRun(task, taskId, status, queuedCount) {
+    this.countRun(status);
     try {
       if (task.oneShot) {
         task.status = 'completed';