alvin-bot 4.25.1 → 5.0.0

package/dist/services/self-diagnosis.js

@@ -0,0 +1,272 @@
+/**
+ * AI-driven Self-Diagnosis (Self-Preservation Phase 2, feature 3I).
+ *
+ * Trigger model — IMPORTANT:
+ *
+ *   3I does NOT run at watchdog-brake time. The bot is mid-exit then;
+ *   spawning a fresh process just to make one AI call would be heavy
+ *   and racy. Instead, 3I runs at the next successful bot start:
+ *   it scans ~/.alvin-bot/diagnostics/ for forensic bundles that don't
+ *   yet have a sidecar .analysis.md file, runs AI analysis on each,
+ *   writes the sidecar, and delivers a Telegram summary via 1D.
+ *
+ *   User-visible consequence: when the bot recovers from a brake, the
+ *   first thing it does after Pre-Flight is analyze why it crashed —
+ *   the operator gets the diagnosis on their phone within ~30 s of
+ *   the bot coming back up.
+ *
+ * Provider-agnostic — uses the active Provider's query() async generator,
+ * works for claude-sdk / codex-cli / groq / gemini / openai / offline-gemma4.
+ * The prompt is deliberately tight (~250 tokens base + bundle content,
+ * truncated to ~12 KB) so even small-context models can handle it.
+ *
+ * Output shape — we force a structured plain-text response (no JSON;
+ * JSON parsing reliability is unever across providers, especially with
+ * smaller models). The 5-line format is hard to mess up:
+ *
+ *   HYPOTHESIS: ...
+ *   ROOT_CAUSE_CATEGORY: ...
+ *   REMEDIATION: ...
+ *   CONFIDENCE: HIGH|MEDIUM|LOW
+ *   EXPLANATION: ...
+ *
+ * Privacy: forensic bundles are already curated by 2F to exclude
+ * secrets (BOT_TOKEN, API keys); only whitelisted non-secret env vars
+ * are included. So the AI request contains: bot version, logs, env
+ * keys (non-secret), tool inventory, disk state. No tokens leave the
+ * machine.
+ *
+ * Auto-remediation policy (v1, intentionally conservative):
+ *   - We NEVER auto-apply any remediation. The AI's REMEDIATION line
+ *     is shown to the operator as a suggestion only.
+ *   - Operator runs it manually if it looks right.
+ *   - This will likely relax in a future release once we build
+ *     confidence in the AI's track record per remediation category.
+ *
+ * Opt-out:
+ *   ALVIN_DISABLE_SELF_DIAGNOSIS=true      → skip 3I specifically
+ *   ALVIN_DISABLE_SELF_PRESERVATION=true   → skip ALL Phase-1/2
+ */
+import { existsSync, readFileSync, writeFileSync, readdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { emitCritical } from "./critical-notify.js";
+const PROMPT_TEMPLATE = `You are an SRE assistant. An Alvin Bot instance hit a critical failure.
+Below is the forensic dump. Read it, then respond in EXACTLY this 5-line format —
+no markdown, no commentary, no extra lines:
+
+HYPOTHESIS: <one short sentence: what likely went wrong>
+ROOT_CAUSE_CATEGORY: <pick ONE: config-error | resource-exhaustion | external-failure | code-bug | environment-conflict | unknown>
+REMEDIATION: <one shell command the operator can run, OR "no automated action available">
+CONFIDENCE: <HIGH | MEDIUM | LOW>
+EXPLANATION: <2-4 sentences explaining your reasoning, plain text>
+
+--- FORENSIC DUMP ---
+{BUNDLE_CONTENT}
+--- END OF DUMP ---`;
+function isDisabled() {
+    return (process.env.ALVIN_DISABLE_SELF_DIAGNOSIS === "true" ||
+        process.env.ALVIN_DISABLE_SELF_PRESERVATION === "true");
+}
+function parseAIResponse(text) {
+    const get = (key) => {
+        // ^KEY: ... up to next \n^KEY:|end. Multiline-safe.
+        const re = new RegExp(`^${key}:\\s*([\\s\\S]*?)(?=^(?:HYPOTHESIS|ROOT_CAUSE_CATEGORY|REMEDIATION|CONFIDENCE|EXPLANATION):|$)`, "m");
+        const m = text.match(re);
+        return m ? m[1].trim() : "";
+    };
+    const conf = get("CONFIDENCE").split(/\s+/)[0]?.toUpperCase() || "";
+    return {
+        hypothesis: get("HYPOTHESIS") || "(no hypothesis returned)",
+        rootCauseCategory: get("ROOT_CAUSE_CATEGORY") || "unknown",
+        remediation: get("REMEDIATION") || "(no remediation)",
+        confidence: (["HIGH", "MEDIUM", "LOW"].includes(conf) ? conf : "UNKNOWN"),
+        explanation: get("EXPLANATION") || "(no explanation)",
+        raw: text,
+    };
+}
+/**
+ * Truncate the forensic bundle to fit within small-context windows.
+ * Keep the first 2 KB (event detail, process state, env) and last 8 KB
+ * (recent logs, where the actual error usually surfaces).
+ */
+function truncateBundle(text, maxChars = 12_000) {
+    if (text.length <= maxChars)
+        return text;
+    const head = text.slice(0, 2000);
+    const tail = text.slice(-(maxChars - 2000 - 50));
+    return `${head}\n\n[... ${text.length - maxChars} chars elided ...]\n\n${tail}`;
+}
+/**
+ * Run AI analysis on a single forensic bundle. Returns null on opt-out,
+ * unparseable response, or provider failure. Side-effects: writes
+ * `<bundlePath>.analysis.md` sidecar with the formatted result.
+ */
+export async function analyzeBundle(bundlePath, registry, opts = {}) {
+    if (isDisabled())
+        return null;
+    if (!existsSync(bundlePath))
+        return null;
+    let provider, activeKey = "(unknown)";
+    try {
+        provider = registry.getActive();
+        activeKey = registry.getActiveKey();
+    }
+    catch {
+        return null;
+    }
+    if (!provider)
+        return null;
+    const t0 = Date.now();
+    const bundleRaw = readFileSync(bundlePath, "utf-8");
+    const bundleClipped = truncateBundle(bundleRaw);
+    const prompt = PROMPT_TEMPLATE.replace("{BUNDLE_CONTENT}", bundleClipped);
+    // Hard timeout — protects against a hung provider call wedging
+    // the bot startup forever. Stream may be aborted mid-flight.
+    const timeoutMs = opts.timeoutMs ?? 120_000;
+    const abortController = new AbortController();
+    const timer = setTimeout(() => abortController.abort(), timeoutMs);
+    let fullText = "";
+    try {
+        for await (const chunk of provider.query({
+            prompt,
+            systemPrompt: "You are a precise SRE assistant. Reply ONLY in the requested format.",
+            abortSignal: abortController.signal,
+        })) {
+            if (chunk.type === "text") {
+                if (chunk.delta)
+                    fullText += chunk.delta;
+                else if (chunk.text)
+                    fullText = chunk.text;
+            }
+            else if (chunk.type === "error") {
+                clearTimeout(timer);
+                return null;
+            }
+            else if (chunk.type === "done") {
+                if (chunk.text)
+                    fullText = chunk.text;
+                break;
+            }
+        }
+    }
+    catch {
+        clearTimeout(timer);
+        return null;
+    }
+    clearTimeout(timer);
+    if (!fullText.trim())
+        return null;
+    const parsed = parseAIResponse(fullText);
+    const result = {
+        ...parsed,
+        durationMs: Date.now() - t0,
+        provider: activeKey,
+    };
+    // Write sidecar — overwrites if user re-runs analysis
+    try {
+        const sidecarPath = bundlePath.replace(/\.md$/, ".analysis.md");
+        writeFileSync(sidecarPath, formatAnalysis(result, bundlePath), { mode: 0o600 });
+    }
+    catch {
+        // Sidecar write failed — non-fatal, we still return the result
+    }
+    return result;
+}
+function formatAnalysis(r, bundlePath) {
+    return [
+        `# AI Self-Diagnosis`,
+        ``,
+        `**Bundle:** \`${bundlePath}\``,
+        `**Generated:** ${new Date().toISOString()}`,
+        `**Provider:** ${r.provider}`,
+        `**Duration:** ${r.durationMs} ms`,
+        ``,
+        `## Hypothesis`,
+        r.hypothesis,
+        ``,
+        `## Root Cause Category`,
+        `\`${r.rootCauseCategory}\``,
+        ``,
+        `## Suggested Remediation`,
+        `\`\`\`bash`,
+        r.remediation,
+        `\`\`\``,
+        `> **Note:** the bot does NOT auto-apply this. Run it yourself only if it makes sense.`,
+        ``,
+        `## Confidence`,
+        `**${r.confidence}**`,
+        ``,
+        `## Explanation`,
+        r.explanation,
+        ``,
+        `---`,
+        ``,
+        `### Raw AI response`,
+        `\`\`\``,
+        r.raw,
+        `\`\`\``,
+        ``,
+    ].join("\n");
+}
+/**
+ * Find diagnostic bundles in ~/.alvin-bot/diagnostics/ that do NOT yet
+ * have a sidecar .analysis.md. Used by the startup scanner.
+ */
+function findUnanalyzedBundles() {
+    const dir = join(homedir(), ".alvin-bot", "diagnostics");
+    if (!existsSync(dir))
+        return [];
+    try {
+        return readdirSync(dir)
+            .filter((f) => f.endsWith(".md") && !f.endsWith(".analysis.md"))
+            .filter((f) => !existsSync(join(dir, f.replace(/\.md$/, ".analysis.md"))))
+            .map((f) => join(dir, f));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Scan for unanalyzed bundles and run AI analysis on each. Designed
+ * to be called once at bot startup, in the background (non-blocking).
+ *
+ * Delivers one Telegram DM per analyzed bundle via the 1D channel,
+ * with the structured findings. Auto-deduplicates: a bundle with an
+ * existing sidecar is skipped.
+ */
+export async function runStartupAnalyzer(registry) {
+    if (isDisabled())
+        return;
+    if (!registry)
+        return;
+    const bundles = findUnanalyzedBundles();
+    if (bundles.length === 0)
+        return;
+    // Process oldest first (FIFO so the operator sees them in order)
+    bundles.sort();
+    console.log(`🧠 Self-diagnosis: ${bundles.length} unanalyzed bundle(s) found — analyzing...`);
+    for (const bundlePath of bundles) {
+        try {
+            const result = await analyzeBundle(bundlePath, registry);
+            if (!result) {
+                console.warn(`   ⚠ ${bundlePath}: analysis returned no result (provider error or opt-out)`);
+                continue;
+            }
+            console.log(`   ✓ ${bundlePath.split("/").pop()} → ${result.rootCauseCategory} (${result.confidence}, ${result.durationMs}ms via ${result.provider})`);
+            // Deliver via 1D — severity warn (informational), not critical
+            emitCritical({
+                category: "custom",
+                severity: "warn",
+                title: `AI diagnosis ready — ${result.rootCauseCategory} (${result.confidence} confidence)`,
+                detail: `Hypothesis: ${result.hypothesis}\n\n` +
+                    `Explanation: ${result.explanation}\n\n` +
+                    `Full analysis: ${bundlePath.replace(/\.md$/, ".analysis.md")}`,
+                suggestedAction: result.remediation,
+            });
+        }
+        catch (err) {
+            console.warn(`   ⚠ ${bundlePath}: analyzer threw — ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}

package/dist/services/trends.js

@@ -0,0 +1,309 @@
+/**
+ * Predictive Maintenance via Trends (Self-Preservation Phase 2, 3J).
+ *
+ * Mechanism:
+ *   1. Once every 24 h: snapshot lightweight health metrics and append
+ *      one JSON line to ~/.alvin-bot/state/trends.jsonl
+ *   2. After the file has ≥ 7 days of data: also run a daily AI
+ *      "anomaly detection" pass over the last 30 days of snapshots
+ *   3. If the AI flags a concerning trend → DM operator via 1D
+ *
+ * Why daily and not continuous: trends are about slow degradation
+ * (memory growth, error-rate increase, crash-frequency drift). A
+ * 24-hour sampling cadence is right for these timescales and keeps
+ * the storage + AI-call cost near zero.
+ *
+ * Storage format — JSONL, one line per day:
+ *
+ *   {"ts": "2026-05-13T04:00:00Z", "uptime_s": 86400, "rss_mb": 105,
+ *    "crashes_24h": 0, "diag_24h": 0, "errors_24h": 3,
+ *    "provider": "claude-sdk", "version": "5.0.0"}
+ *
+ * The JSONL design is deliberate: easy to inspect with tail/head/awk,
+ * easy to truncate to last N days, no parsing pitfalls. The AI gets
+ * the whole tail as plain text — works with small-context models.
+ *
+ * Provider-agnostic — same engine.query() pipeline as 3I.
+ *
+ * Opt-out:
+ *   ALVIN_DISABLE_TRENDS=true              → skip 3J entirely
+ *   ALVIN_DISABLE_SELF_PRESERVATION=true   → skip all Phase-1/2
+ *
+ * Tunable for testing:
+ *   ALVIN_TRENDS_INTERVAL_HOURS=24         → snapshot cadence
+ *   ALVIN_TRENDS_AI_AFTER_DAYS=7           → days of data before AI analysis kicks in
+ */
+import { appendFileSync, existsSync, readFileSync, mkdirSync } from "fs";
+import { join, dirname } from "path";
+import { homedir } from "os";
+import { BOT_VERSION } from "../version.js";
+import { emitCritical } from "./critical-notify.js";
+const TRENDS_PATH = join(homedir(), ".alvin-bot", "state", "trends.jsonl");
+const DEFAULT_INTERVAL_HOURS = 24;
+const DEFAULT_AI_THRESHOLD_DAYS = 7;
+const MAX_RETAIN_DAYS = 90;
+let trendsTimer = null;
+function isDisabled() {
+    return (process.env.ALVIN_DISABLE_TRENDS === "true" ||
+        process.env.ALVIN_DISABLE_SELF_PRESERVATION === "true");
+}
+function countLogLinesLast24h(filename, pattern) {
+    const path = join(homedir(), ".alvin-bot", "logs", filename);
+    if (!existsSync(path))
+        return 0;
+    try {
+        const content = readFileSync(path, "utf-8");
+        const cutoff = Date.now() - 24 * 60 * 60 * 1000;
+        let count = 0;
+        for (const line of content.split("\n")) {
+            const tsMatch = line.match(/^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d+Z)/);
+            if (!tsMatch)
+                continue;
+            const lineTs = new Date(tsMatch[1]).getTime();
+            if (Number.isFinite(lineTs) && lineTs >= cutoff) {
+                if (!pattern || pattern.test(line))
+                    count++;
+            }
+        }
+        return count;
+    }
+    catch {
+        return 0;
+    }
+}
+function readWatchdogCrashes24h() {
+    try {
+        const path = join(homedir(), ".alvin-bot", "state", "watchdog.json");
+        if (!existsSync(path))
+            return 0;
+        const data = JSON.parse(readFileSync(path, "utf-8"));
+        return data.dailyCrashCount ?? 0;
+    }
+    catch {
+        return 0;
+    }
+}
+function countDiagnosticBundlesLast24h() {
+    try {
+        const dir = join(homedir(), ".alvin-bot", "diagnostics");
+        if (!existsSync(dir))
+            return 0;
+        const { readdirSync, statSync } = require("fs");
+        const cutoff = Date.now() - 24 * 60 * 60 * 1000;
+        return readdirSync(dir)
+            .filter((f) => f.endsWith(".md") && !f.endsWith(".analysis.md"))
+            .filter((f) => {
+            try {
+                return statSync(join(dir, f)).mtimeMs >= cutoff;
+            }
+            catch {
+                return false;
+            }
+        }).length;
+    }
+    catch {
+        return 0;
+    }
+}
+function takeSnapshot(activeProvider) {
+    const mem = process.memoryUsage();
+    return {
+        ts: new Date().toISOString(),
+        uptime_s: Math.round(process.uptime()),
+        rss_mb: Math.round(mem.rss / 1024 / 1024),
+        heap_mb: Math.round(mem.heapUsed / 1024 / 1024),
+        crashes_24h: readWatchdogCrashes24h(),
+        diag_24h: countDiagnosticBundlesLast24h(),
+        errors_24h: countLogLinesLast24h("alvin-bot.err.log"),
+        provider: activeProvider,
+        version: BOT_VERSION,
+    };
+}
+function appendSnapshot(snap) {
+    try {
+        mkdirSync(dirname(TRENDS_PATH), { recursive: true });
+        appendFileSync(TRENDS_PATH, JSON.stringify(snap) + "\n");
+    }
+    catch {
+        // Disk full / permissions — non-fatal
+    }
+}
+function readSnapshots(lastN = 30) {
+    if (!existsSync(TRENDS_PATH))
+        return [];
+    try {
+        const content = readFileSync(TRENDS_PATH, "utf-8");
+        const lines = content.split("\n").filter((l) => l.trim());
+        const recent = lines.slice(-lastN);
+        return recent
+            .map((l) => {
+            try {
+                return JSON.parse(l);
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((s) => s !== null);
+    }
+    catch {
+        return [];
+    }
+}
+const TREND_PROMPT_TEMPLATE = `You are an SRE monitoring an Alvin Bot instance over the last days.
+Below is one JSON line per day with the bot's daily health metrics.
+
+Detect any CONCERNING trend that suggests slow degradation — like:
+  - Memory (rss_mb / heap_mb) growing day over day
+  - Error rate (errors_24h) climbing
+  - Crashes (crashes_24h) above 0 for multiple days
+  - Diagnostic bundles (diag_24h) > 0 repeatedly
+
+If there is NO concerning trend, respond with EXACTLY this one line:
+ANOMALY: NONE
+
+If there IS a concerning trend, respond in this 3-line format — nothing else:
+
+ANOMALY: <one short sentence — what trend you noticed>
+SEVERITY: <warn | critical>
+SUGGESTION: <one shell command OR observation for the operator>
+
+--- LAST {N} DAYS OF SNAPSHOTS ---
+{SNAPSHOTS}
+--- END ---`;
+function parseTrendResponse(text) {
+    if (/^ANOMALY:\s*NONE/im.test(text)) {
+        return {
+            anomalyDetected: false,
+            description: "no concerning trend detected",
+            severity: "none",
+            suggestion: "",
+            raw: text,
+        };
+    }
+    const get = (key) => {
+        const m = text.match(new RegExp(`^${key}:\\s*(.+?)$`, "m"));
+        return m ? m[1].trim() : "";
+    };
+    const sevRaw = get("SEVERITY").toLowerCase();
+    const sev = sevRaw === "critical" ? "critical" : "warn";
+    return {
+        anomalyDetected: true,
+        description: get("ANOMALY") || "(no description)",
+        severity: sev,
+        suggestion: get("SUGGESTION") || "(no suggestion)",
+        raw: text,
+    };
+}
+export async function analyzeTrends(registry) {
+    if (isDisabled())
+        return null;
+    if (!registry)
+        return null;
+    const snaps = readSnapshots(30);
+    const threshold = parseInt(process.env.ALVIN_TRENDS_AI_AFTER_DAYS || "", 10) || DEFAULT_AI_THRESHOLD_DAYS;
+    if (snaps.length < threshold)
+        return null;
+    let provider;
+    try {
+        provider = registry.getActive();
+    }
+    catch {
+        return null;
+    }
+    if (!provider)
+        return null;
+    const snapsBlock = snaps.map((s) => JSON.stringify(s)).join("\n");
+    const prompt = TREND_PROMPT_TEMPLATE.replace("{N}", String(snaps.length)).replace("{SNAPSHOTS}", snapsBlock);
+    const abortController = new AbortController();
+    const timer = setTimeout(() => abortController.abort(), 60_000);
+    let fullText = "";
+    try {
+        for await (const chunk of provider.query({
+            prompt,
+            systemPrompt: "You are a precise SRE assistant. Reply ONLY in the requested format.",
+            abortSignal: abortController.signal,
+        })) {
+            if (chunk.type === "text") {
+                if (chunk.delta)
+                    fullText += chunk.delta;
+                else if (chunk.text)
+                    fullText = chunk.text;
+            }
+            else if (chunk.type === "error") {
+                clearTimeout(timer);
+                return null;
+            }
+            else if (chunk.type === "done") {
+                if (chunk.text)
+                    fullText = chunk.text;
+                break;
+            }
+        }
+    }
+    catch {
+        clearTimeout(timer);
+        return null;
+    }
+    clearTimeout(timer);
+    if (!fullText.trim())
+        return null;
+    return parseTrendResponse(fullText);
+}
+async function dailyTask(registry) {
+    try {
+        // Snapshot first — always, regardless of AI being available
+        const activeProviderKey = (() => {
+            try {
+                return registry?.getActiveKey() || "none";
+            }
+            catch {
+                return "none";
+            }
+        })();
+        const snap = takeSnapshot(activeProviderKey);
+        appendSnapshot(snap);
+        console.log(`📊 Trends snapshot taken: rss=${snap.rss_mb}MB errors=${snap.errors_24h} crashes=${snap.crashes_24h}`);
+        // Then attempt AI analysis if we have enough history
+        const result = await analyzeTrends(registry);
+        if (!result)
+            return;
+        if (!result.anomalyDetected) {
+            console.log(`📊 Trends AI: no anomaly detected`);
+            return;
+        }
+        console.log(`📊 Trends AI: ANOMALY (${result.severity}) — ${result.description}`);
+        emitCritical({
+            category: "custom",
+            severity: result.severity === "critical" ? "critical" : "warn",
+            title: `Trend anomaly detected: ${result.description}`,
+            detail: `30-day trend analysis flagged a concerning pattern.\n\n` +
+                `Suggestion: ${result.suggestion}\n\n` +
+                `Trend data: ${TRENDS_PATH}`,
+            suggestedAction: result.suggestion,
+        });
+    }
+    catch (err) {
+        console.warn(`📊 Trends daily task threw: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+export function startTrendsCollector(registry) {
+    if (isDisabled())
+        return;
+    const intervalH = parseInt(process.env.ALVIN_TRENDS_INTERVAL_HOURS || "", 10) || DEFAULT_INTERVAL_HOURS;
+    const intervalMs = intervalH * 60 * 60 * 1000;
+    // Initial: take a first snapshot after 60 s to avoid measuring the
+    // startup transient. Subsequent snapshots every intervalMs.
+    setTimeout(() => {
+        void dailyTask(registry);
+        trendsTimer = setInterval(() => void dailyTask(registry), intervalMs);
+        if (trendsTimer.unref)
+            trendsTimer.unref();
+    }, 60_000);
+}
+export function stopTrendsCollector() {
+    if (trendsTimer) {
+        clearInterval(trendsTimer);
+        trendsTimer = null;
+    }
+}

package/dist/services/watchdog.js

@@ -27,6 +27,8 @@ import { resolve } from "path";
 import os from "os";
 import { execSync } from "child_process";
 import { BOT_VERSION } from "../version.js";
+import { emitCritical } from "./critical-notify.js";
+import { writeDiagnosticBundle } from "./auto-diagnostic.js";
 import { decideBrakeAction, shouldResetCrashCounter, DEFAULTS, } from "./watchdog-brake.js";
 const DATA_DIR = process.env.ALVIN_DATA_DIR || resolve(os.homedir(), ".alvin-bot");
 const STATE_DIR = resolve(DATA_DIR, "state");
@@ -164,6 +166,51 @@ export function startWatchdog() {
     if (decision.action === "brake") {
         console.error(`[watchdog] crash-loop brake triggered: ${decision.reason}`);
         writeAlert(decision.reason, previous?.crashCount ?? 0);
+        // Critical-event notify (Self-Preservation Phase 1, feature 1D).
+        // emitCritical is synchronous-fast (file flag + osascript inline)
+        // and schedules a detached Telegram DM via curl that survives the
+        // process.exit(3) below — exactly the case this mechanism was
+        // built for.
+        // Auto-diagnostic (feature 2F) — collect forensic bundle BEFORE
+        // emitCritical so the Telegram DM can reference the file path.
+        let bundlePath = null;
+        try {
+            bundlePath = writeDiagnosticBundle({
+                category: "watchdog-brake",
+                severity: "critical",
+                title: "Watchdog crash-loop brake engaged",
+                detail: `${decision.reason}\n` +
+                    `Bot version: ${BOT_VERSION}`,
+                suggestedAction: `rm "${ALERT_FILE}" && alvin-bot launchd install`,
+            });
+            if (bundlePath) {
+                console.error(`[auto-diagnostic] forensic bundle written: ${bundlePath}`);
+            }
+        }
+        catch (err) {
+            console.error("[watchdog] auto-diagnostic failed:", err);
+        }
+        try {
+            emitCritical({
+                category: "watchdog-brake",
+                severity: "critical",
+                title: "Watchdog crash-loop brake engaged",
+                detail: `${decision.reason}\n` +
+                    `Bot version: ${BOT_VERSION}\n` +
+                    `The bot has stopped itself to prevent further damage.` +
+                    (bundlePath ? `\n\nDiagnostic bundle: ${bundlePath}` : ""),
+                suggestedAction: `rm "${ALERT_FILE}" && alvin-bot launchd install`,
+            }, {
+                // We're about to process.exit(3). Block on the Telegram POST
+                // synchronously — detached spawn races the exit on macOS+launchd
+                // and the alert silently never lands. Adds ~1-2 s before exit;
+                // worth it to actually inform the user their bot just braked.
+                blockTelegram: true,
+            });
+        }
+        catch (err) {
+            console.error("[watchdog] critical-notify failed:", err);
+        }
         // checkCrashLoopBrake tries to unload the LaunchAgent so launchd stops
         // retrying. It only runs the exit path if ALERT_FILE exists, which is
         // normally true after writeAlert — but if writeAlert failed silently

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alvin-bot",
-  "version": "4.25.1",
+  "version": "5.0.0",
   "description": "Alvin Bot — Your personal AI agent on Telegram, WhatsApp, Discord, Signal, and Web.",
   "type": "module",
   "main": "dist/index.js",