clementine-agent 1.0.16 → 1.0.18

package/dist/cli/dashboard.js

@@ -16201,11 +16201,39 @@ async function refreshBrokenJobs() {
       var agentTag = j.agentSlug
         ? '<span class="badge badge-blue" style="font-size:10px">' + esc(j.agentSlug) + '</span>'
         : '';
+
+      // Diagnosis block — root cause + proposed fix + diff preview.
+      var diagnosisHtml = '';
+      if (j.diagnosis) {
+        var riskColor = j.diagnosis.riskLevel === 'high' ? '#ef4444'
+          : j.diagnosis.riskLevel === 'medium' ? '#f59e0b' : '#22c55e';
+        var confLabel = j.diagnosis.confidence !== 'high'
+          ? ' <span style="font-size:10px;color:var(--text-muted)">(' + esc(j.diagnosis.confidence) + ' confidence)</span>'
+          : '';
+        var diffHtml = '';
+        if (j.diagnosis.proposedFix.diff) {
+          diffHtml = '<pre style="font-size:11px;background:#0f172a;color:#e2e8f0;padding:8px;border-radius:4px;margin:6px 0 0;white-space:pre-wrap;word-break:break-word;max-height:200px;overflow-y:auto">'
+            + esc(j.diagnosis.proposedFix.diff) + '</pre>';
+        }
+        diagnosisHtml = '<div style="margin-top:10px;padding:10px;border-left:3px solid ' + riskColor
+          + ';background:var(--bg-tertiary);border-radius:4px">'
+          + '<div style="font-size:12px;margin-bottom:4px"><strong>Root cause' + confLabel + ':</strong> '
+          + esc(j.diagnosis.rootCause) + '</div>'
+          + '<div style="font-size:12px"><strong>Proposed fix:</strong> '
+          + esc(j.diagnosis.proposedFix.details) + '</div>'
+          + diffHtml
+          + '<div style="font-size:10px;color:var(--text-muted);margin-top:6px">'
+          + esc(j.diagnosis.proposedFix.type) + ' \\u00b7 ' + esc(j.diagnosis.riskLevel) + ' risk \\u00b7 diagnosed ' + timeAgo(j.diagnosis.generatedAt)
+          + '</div>'
+          + '</div>';
+      }
+
       html += '<div style="padding:12px;border:1px solid var(--border);border-radius:8px;background:var(--bg-secondary)">'
         + '<div style="display:flex;align-items:center;gap:8px;flex-wrap:wrap">'
         + '<strong>' + esc(j.jobName) + '</strong> ' + agentTag + ' ' + breaker
         + '<span style="margin-left:auto;font-size:11px;color:var(--text-muted)">' + failureRatio + ' failed \\u00b7 last error ' + lastErrorAt + '</span>'
         + '</div>'
+        + diagnosisHtml
         + errorsHtml
         + advisorLine
         + '</div>';

package/dist/gateway/failure-diagnostics.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Clementine TypeScript — Broken-job diagnostic agent.
+ *
+ * When the failure monitor flags a job, this runs a cheap Haiku-level
+ * analysis over the job definition, agent profile, and recent runs to
+ * propose a root cause and a specific fix. Read-only: it never writes
+ * anything except its own cache.
+ *
+ * Output surfaces in the Broken Jobs dashboard panel and the owner DM
+ * so the response to a silent failure is "here's what's wrong and
+ * here's what to change" rather than "go investigate."
+ */
+import type { Gateway } from './router.js';
+import type { BrokenJob } from './failure-monitor.js';
+export interface Diagnosis {
+    rootCause: string;
+    confidence: 'high' | 'medium' | 'low';
+    proposedFix: {
+        type: 'config_change' | 'prompt_change' | 'agent_scope' | 'disable' | 'credential_refresh' | 'escalate_to_owner';
+        details: string;
+        diff?: string;
+    };
+    riskLevel: 'low' | 'medium' | 'high';
+    generatedAt: string;
+}
+/**
+ * Diagnose one broken job. Returns a cached diagnosis if one exists and is
+ * fresher than 24h; otherwise invokes the LLM. Always best-effort — returns
+ * null instead of throwing so failure detection stays robust.
+ */
+export declare function diagnoseBrokenJob(broken: BrokenJob, gateway: Gateway): Promise<Diagnosis | null>;
+/**
+ * Clear cached diagnosis for a job (e.g., after the owner applies a fix).
+ * Called opportunistically when a broken job disappears from the live set.
+ */
+export declare function clearDiagnosis(jobName: string): void;
+/** Read-only accessor for the dashboard. */
+export declare function getDiagnosisIfFresh(jobName: string): Diagnosis | null;
+//# sourceMappingURL=failure-diagnostics.d.ts.map

package/dist/gateway/failure-diagnostics.js

@@ -0,0 +1,257 @@
+/**
+ * Clementine TypeScript — Broken-job diagnostic agent.
+ *
+ * When the failure monitor flags a job, this runs a cheap Haiku-level
+ * analysis over the job definition, agent profile, and recent runs to
+ * propose a root cause and a specific fix. Read-only: it never writes
+ * anything except its own cache.
+ *
+ * Output surfaces in the Broken Jobs dashboard panel and the owner DM
+ * so the response to a silent failure is "here's what's wrong and
+ * here's what to change" rather than "go investigate."
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
+import path from 'node:path';
+import pino from 'pino';
+import { AGENTS_DIR, BASE_DIR, CRON_FILE } from '../config.js';
+const logger = pino({ name: 'clementine.failure-diagnostics' });
+const CACHE_FILE = path.join(BASE_DIR, 'cron', 'failure-diagnostics.json');
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const RUNS_DIR = path.join(BASE_DIR, 'cron', 'runs');
+function loadCache() {
+    try {
+        if (!existsSync(CACHE_FILE))
+            return {};
+        const raw = JSON.parse(readFileSync(CACHE_FILE, 'utf-8'));
+        return raw;
+    }
+    catch {
+        return {};
+    }
+}
+function saveCache(cache) {
+    try {
+        mkdirSync(path.dirname(CACHE_FILE), { recursive: true });
+        writeFileSync(CACHE_FILE, JSON.stringify(cache, null, 2));
+    }
+    catch (err) {
+        logger.warn({ err }, 'Failed to persist diagnostic cache');
+    }
+}
+/**
+ * Pull the raw YAML entry for a cron job from CRON.md (global or agent-scoped).
+ * Returns the text of the entry, not the parsed object, so the diagnostic
+ * agent sees the exact fields the user edits.
+ */
+function readJobDefinition(jobName) {
+    const [maybeSlug, ...rest] = jobName.split(':');
+    const bareName = rest.length > 0 ? rest.join(':') : maybeSlug;
+    const candidateFiles = [];
+    if (rest.length > 0) {
+        // agent-scoped: ross-the-sdr:reply-detection
+        candidateFiles.push(path.join(AGENTS_DIR, maybeSlug, 'CRON.md'));
+    }
+    candidateFiles.push(CRON_FILE);
+    for (const file of candidateFiles) {
+        if (!existsSync(file))
+            continue;
+        try {
+            const raw = readFileSync(file, 'utf-8');
+            // Find the YAML block for "- name: bareName" and return until the next
+            // "- name:" at the same indent or end of file.
+            const pattern = new RegExp(`^(  - name: ${bareName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*$[\\s\\S]*?)(?=^  - name: |\\z)`, 'm');
+            const m = raw.match(pattern);
+            if (m)
+                return m[1].slice(0, 6000);
+        }
+        catch { /* skip */ }
+    }
+    return null;
+}
+/**
+ * Read the agent profile markdown if this job is scoped to an agent.
+ * Returns the first 2K chars which covers name/description/tier/allowedTools.
+ */
+function readAgentProfile(agentSlug) {
+    const profile = path.join(AGENTS_DIR, agentSlug, 'agent.md');
+    if (!existsSync(profile))
+        return null;
+    try {
+        return readFileSync(profile, 'utf-8').slice(0, 2500);
+    }
+    catch {
+        return null;
+    }
+}
+/** Last N cron run entries for the job, oldest → newest for the prompt. */
+function readRecentRuns(jobName, limit = 10) {
+    const safe = jobName.replace(/[^a-zA-Z0-9_-]/g, '_');
+    const file = path.join(RUNS_DIR, `${safe}.jsonl`);
+    if (!existsSync(file))
+        return '(no run log)';
+    try {
+        const lines = readFileSync(file, 'utf-8').trim().split('\n').filter(Boolean);
+        const recent = lines.slice(-limit);
+        const summaries = recent.map(line => {
+            try {
+                const d = JSON.parse(line);
+                const detail = d.status === 'ok'
+                    ? `preview="${(d.outputPreview ?? '').slice(0, 120).replace(/\n/g, ' ')}"`
+                    : `error="${(d.error ?? '').split('\n')[0].slice(0, 160)}"`;
+                return `${d.startedAt} ${d.status} (${Math.round(d.durationMs / 1000)}s) ${detail}`;
+            }
+            catch {
+                return line.slice(0, 160);
+            }
+        });
+        return summaries.join('\n');
+    }
+    catch {
+        return '(failed to read run log)';
+    }
+}
+function buildPrompt(broken, jobDef, agentProfile, recentRuns) {
+    const breakerLine = broken.circuitBreakerEngagedAt
+        ? `Circuit breaker engaged at ${broken.circuitBreakerEngagedAt}.`
+        : 'No active circuit breaker.';
+    return [
+        `You are a reliability engineer diagnosing a cron job that's been failing in Clementine (a personal AI assistant framework).`,
+        `Your output must be a single JSON object with the schema shown at the end. No preamble, no postscript.`,
+        '',
+        `## Job name: ${broken.jobName}`,
+        broken.agentSlug ? `## Agent scope: ${broken.agentSlug}` : '## Scope: global (no agent)',
+        `## Failure stats: ${broken.errorCount48h}/${broken.totalRuns48h} runs failed in last 48h. ${breakerLine}`,
+        broken.lastAdvisorOpinion ? `## Advisor notes: ${broken.lastAdvisorOpinion}` : '',
+        '',
+        '## Job definition (CURRENT state of CRON.md):',
+        jobDef ?? '(not found in CRON.md — may be a heartbeat pseudo-job like insight-check)',
+        '',
+        agentProfile ? '## Agent profile (agent.md, truncated):\n' + agentProfile + '\n' : '',
+        '## Recent runs (oldest → newest):',
+        recentRuns,
+        '',
+        broken.lastErrors.length > 0 ? '## Distinct recent errors:\n' + broken.lastErrors.map(e => '- ' + e.slice(0, 400)).join('\n') : '',
+        '',
+        '## Critical reasoning rules',
+        '',
+        '**The CURRENT job definition above may differ from the config at the time of past failures.** If you see old errors (e.g. "timeout kill") but the current config ALREADY contains the fields that would have caused those errors, treat those errors as resolved by a recent fix — do NOT propose re-adding the fields that caused them.',
+        '',
+        '**Look at the MOST RECENT runs specifically.** If the last 2+ runs succeeded, the job has recovered — propose `escalate_to_owner` with "appears recovered, no fix needed" as details, confidence: high, risk: low.',
+        '',
+        '**Don\'t propose reverting a fix.** If the current config does NOT contain `mode: unleashed` but recent runs show "Claude Code process aborted by user", do NOT propose adding `mode: unleashed` back. That error pattern occurs in BOTH unleashed (hit max_hours) and standard (hit timeoutMs) modes. Without strong evidence the current config is wrong, prefer raising `timeoutMs` or adding `max_turns` over toggling `mode`.',
+        '',
+        '## Diagnostic patterns (use these as priors)',
+        '',
+        '- **"API 400 input_schema"** → external MCP server exposes a malformed tool. Propose checking claude_desktop_config.json and ~/.claude.json for recently-updated packages. Type: escalate_to_owner.',
+        '- **401/403 errors** → credential refresh needed. Type: credential_refresh. Name the specific service if possible.',
+        '- **"Claude Code process aborted by user" with long durations (>60s)** → timeout kill. If current config has `mode: unleashed`, propose removing it + adding `max_turns: 25`. If current config is already standard, propose raising `timeoutMs` or investigating the prompt for infinite loops.',
+        '- **"Reached maximum number of turns (N)"** → maxTurns set too low for the job\'s tool fan-out. Propose raising `max_turns` to 3×N.',
+        '- **Output preview contains BLOCKED / "no local bash" / "permission denied"** → agent picked the wrong tool. Propose either scoping the job to an agent whose allowedTools excludes the bad MCP, or adding explicit tool-choice guidance in the prompt.',
+        '- **No clear pattern** → escalate_to_owner with what you would need to know.',
+        '',
+        '## Output schema (JSON only, no markdown fences):',
+        '{',
+        '  "rootCause": "1-2 sentences explaining WHY the job is failing, referencing specific fields or error patterns from the CURRENT config",',
+        '  "confidence": "high|medium|low",',
+        '  "proposedFix": {',
+        '    "type": "config_change|prompt_change|agent_scope|disable|credential_refresh|escalate_to_owner",',
+        '    "details": "prose description of the fix, citing the exact field(s) to change",',
+        '    "diff": "optional: exact before/after diff if it is a small config edit"',
+        '  },',
+        '  "riskLevel": "low|medium|high"',
+        '}',
+    ].filter(Boolean).join('\n');
+}
+function parseResponse(raw) {
+    try {
+        // The model sometimes wraps the JSON in markdown fences; extract the
+        // first top-level {...} object.
+        const match = raw.match(/\{[\s\S]*\}/);
+        if (!match)
+            return null;
+        const parsed = JSON.parse(match[0]);
+        if (!parsed.rootCause || !parsed.proposedFix)
+            return null;
+        return {
+            rootCause: String(parsed.rootCause).slice(0, 500),
+            confidence: (parsed.confidence ?? 'medium'),
+            proposedFix: {
+                type: (parsed.proposedFix.type ?? 'escalate_to_owner'),
+                details: String(parsed.proposedFix.details ?? '').slice(0, 800),
+                diff: parsed.proposedFix.diff ? String(parsed.proposedFix.diff).slice(0, 1000) : undefined,
+            },
+            riskLevel: (parsed.riskLevel ?? 'medium'),
+            generatedAt: new Date().toISOString(),
+        };
+    }
+    catch (err) {
+        logger.warn({ err }, 'Failed to parse diagnostic JSON');
+        return null;
+    }
+}
+/**
+ * Diagnose one broken job. Returns a cached diagnosis if one exists and is
+ * fresher than 24h; otherwise invokes the LLM. Always best-effort — returns
+ * null instead of throwing so failure detection stays robust.
+ */
+export async function diagnoseBrokenJob(broken, gateway) {
+    const cache = loadCache();
+    const cached = cache[broken.jobName];
+    if (cached) {
+        const age = Date.now() - Date.parse(cached.generatedAt);
+        if (Number.isFinite(age) && age < CACHE_TTL_MS) {
+            logger.debug({ job: broken.jobName, ageMin: Math.round(age / 60000) }, 'Using cached diagnosis');
+            return cached;
+        }
+    }
+    const jobDef = readJobDefinition(broken.jobName);
+    const agentProfile = broken.agentSlug ? readAgentProfile(broken.agentSlug) : null;
+    const recentRuns = readRecentRuns(broken.jobName, 10);
+    const prompt = buildPrompt(broken, jobDef, agentProfile, recentRuns);
+    let rawResponse;
+    try {
+        rawResponse = await gateway.handleCronJob(`diagnose:${broken.jobName}`, prompt, 1, // tier 1 — cheap
+        5, // maxTurns — diagnosis doesn't need tools typically
+        'haiku');
+    }
+    catch (err) {
+        logger.warn({ err, job: broken.jobName }, 'Diagnostic LLM call failed');
+        return null;
+    }
+    const diagnosis = parseResponse(rawResponse);
+    if (!diagnosis) {
+        logger.warn({ job: broken.jobName, rawHead: rawResponse.slice(0, 200) }, 'Diagnosis returned unparseable response');
+        return null;
+    }
+    cache[broken.jobName] = diagnosis;
+    saveCache(cache);
+    logger.info({
+        job: broken.jobName,
+        confidence: diagnosis.confidence,
+        fixType: diagnosis.proposedFix.type,
+    }, 'Broken-job diagnosis generated');
+    return diagnosis;
+}
+/**
+ * Clear cached diagnosis for a job (e.g., after the owner applies a fix).
+ * Called opportunistically when a broken job disappears from the live set.
+ */
+export function clearDiagnosis(jobName) {
+    const cache = loadCache();
+    if (cache[jobName]) {
+        delete cache[jobName];
+        saveCache(cache);
+    }
+}
+/** Read-only accessor for the dashboard. */
+export function getDiagnosisIfFresh(jobName) {
+    const cache = loadCache();
+    const d = cache[jobName];
+    if (!d)
+        return null;
+    const age = Date.now() - Date.parse(d.generatedAt);
+    if (!Number.isFinite(age) || age >= CACHE_TTL_MS)
+        return null;
+    return d;
+}
+//# sourceMappingURL=failure-diagnostics.js.map

package/dist/gateway/failure-monitor.d.ts

@@ -24,6 +24,18 @@ export interface BrokenJob {
     lastErrors: string[];
     circuitBreakerEngagedAt: string | null;
     lastAdvisorOpinion: string | null;
+    /** Populated asynchronously by the diagnostic agent when available. */
+    diagnosis?: {
+        rootCause: string;
+        confidence: 'high' | 'medium' | 'low';
+        proposedFix: {
+            type: string;
+            details: string;
+            diff?: string;
+        };
+        riskLevel: 'low' | 'medium' | 'high';
+        generatedAt: string;
+    };
 }
 /**
  * Compute the current set of broken jobs by scanning all run logs.
@@ -32,9 +44,14 @@ export interface BrokenJob {
 export declare function computeBrokenJobs(now?: number): BrokenJob[];
 /**
  * Run a sweep: identify currently-broken jobs, pick the ones we haven't
- * notified about recently, and dispatch one consolidated DM.
+ * notified about recently, invoke the diagnostic agent for new entries,
+ * and dispatch one consolidated DM.
+ *
+ * `gateway` is optional — omitted for tests that want to skip the LLM call.
+ * When present, we diagnose fresh broken jobs before notifying, so the
+ * report includes a root-cause + proposed fix for each.
  *
  * Returns the jobs that triggered a fresh notification (mostly for tests/logs).
  */
-export declare function runFailureSweep(send: (text: string) => Promise<unknown>, now?: number): Promise<BrokenJob[]>;
+export declare function runFailureSweep(send: (text: string) => Promise<unknown>, gateway?: import('./router.js').Gateway, now?: number): Promise<BrokenJob[]>;
 //# sourceMappingURL=failure-monitor.d.ts.map

package/dist/gateway/failure-monitor.js

@@ -175,7 +175,20 @@ export function computeBrokenJobs(now = Date.now()) {
         const lastRunMs = Date.parse(lastEntry.startedAt);
         // Always consult the breaker state — a stuck breaker is the primary
         // signal for "job has been silently broken for days".
-        const cb = lastCircuitBreakerEvent(jobName);
+        let cb = lastCircuitBreakerEvent(jobName);
+        // Clear a "stuck" breaker flag if we see an ok run AFTER the last
+        // breaker engagement. The scheduler only logs a circuit-recovery
+        // event when consecutiveErrors >= 5 at recovery time — but a
+        // successful manual/probe run resets consecutiveErrors to 0 first,
+        // so the recovery branch never fires and the advisor log keeps the
+        // breaker appearing engaged forever. Fix: use run-log truth instead.
+        if (cb.engagedAt) {
+            const engagedMs = Date.parse(cb.engagedAt);
+            const hasOkSinceBreaker = entries.some(e => e.status === 'ok' && Date.parse(e.startedAt) > engagedMs);
+            if (hasOkSinceBreaker) {
+                cb = { engagedAt: null, lastOpinion: cb.lastOpinion };
+            }
+        }
         if (!cb.engagedAt && Number.isFinite(lastRunMs) && lastRunMs < dormantCutoffMs) {
             continue;
         }
@@ -244,8 +257,30 @@ export function computeBrokenJobs(now = Date.now()) {
         const bT = b.lastErrorAt ? Date.parse(b.lastErrorAt) : 0;
         return bT - aT;
     });
+    // Attach any cached diagnosis (fresh within 24h). Reads the cache file
+    // directly — avoids circular imports with failure-diagnostics.
+    attachCachedDiagnoses(broken, now);
     return broken;
 }
+const DIAGNOSTICS_CACHE_FILE = path.join(BASE_DIR, 'cron', 'failure-diagnostics.json');
+const DIAGNOSIS_TTL_MS = 24 * 60 * 60 * 1000;
+function attachCachedDiagnoses(jobs, now) {
+    if (!existsSync(DIAGNOSTICS_CACHE_FILE))
+        return;
+    try {
+        const cache = JSON.parse(readFileSync(DIAGNOSTICS_CACHE_FILE, 'utf-8'));
+        for (const j of jobs) {
+            const d = cache[j.jobName];
+            if (!d)
+                continue;
+            const age = now - Date.parse(d.generatedAt);
+            if (Number.isFinite(age) && age < DIAGNOSIS_TTL_MS) {
+                j.diagnosis = d;
+            }
+        }
+    }
+    catch { /* cache may be malformed — ignore */ }
+}
 /**
  * The self-improve loop writes to its own experiment-log.jsonl, not cron/runs/.
  * Its breakage pattern is: state.lastRunAt keeps getting updated nightly but
@@ -338,12 +373,28 @@ function formatReport(jobs) {
     for (const j of jobs) {
         const breaker = j.circuitBreakerEngagedAt ? ' · circuit breaker engaged' : '';
         lines.push(`• \`${j.jobName}\` — ${j.errorCount48h}/${j.totalRuns48h} runs failed${breaker}`);
-        if (j.lastErrors.length > 0) {
-            const preview = j.lastErrors[0].split('\n')[0].slice(0, 140);
-            lines.push(`  Last error: ${preview}`);
+        // Prefer the diagnostic agent's analysis when available — it's more
+        // actionable than the raw error. Fall back to error + advisor lines.
+        if (j.diagnosis) {
+            const conf = j.diagnosis.confidence === 'high' ? '' : ` (${j.diagnosis.confidence} confidence)`;
+            lines.push(`  **Cause${conf}:** ${j.diagnosis.rootCause.slice(0, 240)}`);
+            lines.push(`  **Proposed fix:** ${j.diagnosis.proposedFix.details.slice(0, 240)}`);
+            if (j.diagnosis.proposedFix.diff) {
+                // Show a short diff preview inline; full diff in the dashboard.
+                const diffShort = j.diagnosis.proposedFix.diff.split('\n').slice(0, 4).join('\n');
+                lines.push('  ```diff');
+                lines.push('  ' + diffShort.replace(/\n/g, '\n  '));
+                lines.push('  ```');
+            }
         }
-        if (j.lastAdvisorOpinion) {
-            lines.push(`  Advisor: ${j.lastAdvisorOpinion.slice(0, 140)}`);
+        else {
+            if (j.lastErrors.length > 0) {
+                const preview = j.lastErrors[0].split('\n')[0].slice(0, 140);
+                lines.push(`  Last error: ${preview}`);
+            }
+            if (j.lastAdvisorOpinion) {
+                lines.push(`  Advisor: ${j.lastAdvisorOpinion.slice(0, 140)}`);
+            }
         }
     }
     lines.push('');
@@ -352,24 +403,40 @@ function formatReport(jobs) {
 }
 /**
  * Run a sweep: identify currently-broken jobs, pick the ones we haven't
- * notified about recently, and dispatch one consolidated DM.
+ * notified about recently, invoke the diagnostic agent for new entries,
+ * and dispatch one consolidated DM.
+ *
+ * `gateway` is optional — omitted for tests that want to skip the LLM call.
+ * When present, we diagnose fresh broken jobs before notifying, so the
+ * report includes a root-cause + proposed fix for each.
  *
  * Returns the jobs that triggered a fresh notification (mostly for tests/logs).
  */
-export async function runFailureSweep(send, now = Date.now()) {
+export async function runFailureSweep(send, gateway, now = Date.now()) {
     const broken = computeBrokenJobs(now);
     if (broken.length === 0) {
-        // Clear cooldowns for jobs that recovered so future failures notify promptly.
+        // Clear cooldowns AND diagnostic cache entries for jobs that recovered.
         const state = loadState();
         let mutated = false;
+        const healedJobs = [];
         for (const name of Object.keys(state.notified)) {
             if (!broken.find(b => b.jobName === name)) {
                 delete state.notified[name];
+                healedJobs.push(name);
                 mutated = true;
             }
         }
         if (mutated)
             saveState(state);
+        // Opportunistically drop diagnosis cache for healed jobs
+        if (healedJobs.length > 0) {
+            try {
+                const { clearDiagnosis } = await import('./failure-diagnostics.js');
+                for (const name of healedJobs)
+                    clearDiagnosis(name);
+            }
+            catch { /* non-fatal */ }
+        }
         return [];
     }
     const state = loadState();
@@ -383,6 +450,29 @@ export async function runFailureSweep(send, now = Date.now()) {
     }
     if (fresh.length === 0)
         return [];
+    // Diagnose fresh broken jobs before DMing. Each call is cached 24h, so a
+    // recurring failure doesn't re-invoke the LLM. Diagnosis is best-effort —
+    // if it fails or the gateway isn't wired, the report still goes out.
+    if (gateway) {
+        try {
+            const { diagnoseBrokenJob } = await import('./failure-diagnostics.js');
+            for (const job of fresh) {
+                if (job.diagnosis)
+                    continue; // already attached from cache
+                try {
+                    const d = await diagnoseBrokenJob(job, gateway);
+                    if (d)
+                        job.diagnosis = d;
+                }
+                catch (err) {
+                    logger.warn({ err, job: job.jobName }, 'Diagnosis attempt failed');
+                }
+            }
+        }
+        catch (err) {
+            logger.warn({ err }, 'Failed to load diagnostics module');
+        }
+    }
     try {
         await send(formatReport(fresh));
         const stamp = new Date(now).toISOString();

package/dist/gateway/heartbeat-scheduler.js

@@ -105,8 +105,10 @@ export class HeartbeatScheduler {
         }
         // Cron failure sweep — surface jobs that have been silently failing.
         // Runs every tick; per-job 24h cooldown lives inside the monitor.
+        // Passes the gateway so freshly-broken jobs get a diagnostic LLM call
+        // (cached 24h) before the DM goes out.
         import('./failure-monitor.js').then(({ runFailureSweep }) => {
-            runFailureSweep((text) => this.dispatcher.send(text, {})).catch(err => {
+            runFailureSweep((text) => this.dispatcher.send(text, {}), this.gateway).catch(err => {
                 logger.warn({ err }, 'Failure sweep failed');
             });
         }).catch(err => logger.warn({ err }, 'Failure sweep import failed'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clementine-agent",
-  "version": "1.0.16",
+  "version": "1.0.18",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",