alvin-bot 4.25.1 → 5.0.0

package/CHANGELOG.md

@@ -2,6 +2,173 @@
 
 All notable changes to Alvin Bot are documented here.
 
+## [5.0.0] — 2026-05-13
+
+### Self-Preservation Phase 2 — the bot now reasons about its own failures
+
+The bot now uses **its own AI provider** (whichever one you have configured — claude-sdk, codex-cli, groq, gemini, openai, ollama/gemma4, openrouter, nvidia-nim) to analyze why it failed and where it's heading. Two new features, both event-driven, both opt-out.
+
+The major-version bump reflects a conceptual shift: AI is now part of the bot's **operational loop** about itself, not just the user-facing chat. The feature surface is backwards-compatible — existing setups keep running unchanged; everything new is additive and opt-out via env vars.
+
+#### AI-driven Self-Diagnosis on bundles (feature 3I)
+
+When the watchdog brake fires and 2F writes a forensic bundle, 3I picks up the analysis at **the next successful bot start**:
+
+1. Bot starts → Pre-Flight runs → 3I scans `~/.alvin-bot/diagnostics/` for unanalyzed bundles
+2. For each bundle without a `.analysis.md` sidecar, send it (clipped to ~12 KB, head+tail) to the active AI provider via `provider.query()`
+3. AI returns a structured 5-line response — `HYPOTHESIS / ROOT_CAUSE_CATEGORY / REMEDIATION / CONFIDENCE / EXPLANATION`
+4. Result is written as `.analysis.md` sidecar AND delivered to the operator via 1D Telegram DM
+
+The 5-line plain-text format was chosen over JSON because **JSON parsing reliability is uneven across providers**, especially with smaller models. The format is hard to mess up — and we parse it with a tolerant regex.
+
+Live verified on Apple Silicon with `claude-sdk`: bundle from the actual brake earlier that day was analyzed correctly — AI identified "skills-reload triggered repeated graceful restarts that tripped the brake", suggested the documented recovery command (`rm crash-loop.alert && alvin-bot launchd install`), all within ~9 s.
+
+**Safety policy v1**: the AI's suggested remediation is shown to the operator but **NEVER auto-applied**. This is intentional — we want a track record of accurate suggestions before granting the bot any self-modifying power.
+
+#### Predictive Maintenance via Trends (feature 3J)
+
+A second daily timer writes a one-line JSON snapshot of bot health to `~/.alvin-bot/state/trends.jsonl`:
+
+```jsonl
+{"ts":"2026-05-13T...","uptime_s":86400,"rss_mb":105,"heap_mb":33,"crashes_24h":0,"diag_24h":0,"errors_24h":3,"provider":"claude-sdk","version":"5.0.0"}
+```
+
+After 7 days of data accumulate, every daily snapshot also triggers an AI **anomaly-detection pass** over the last 30 days. Output is a strict 3-line format — `ANOMALY: ... / SEVERITY: warn|critical / SUGGESTION: ...`, or just `ANOMALY: NONE` when nothing's concerning.
+
+Live verified with synthetic 30-day memory-leak data (RSS climbing 100 → 220 MB linearly): `claude-sdk` correctly identified the leak, classified as `critical`, suggested heap-snapshot capture via `kill -USR2`. Confirmed end-to-end with file flag + Telegram DM delivered via 1D.
+
+#### Provider-agnostic by design
+
+Both 3I and 3J use the existing `provider.query()` abstraction — the same code path the bot uses for normal chat. Switching provider via `alvin-bot provider switch <key>` (added in 4.24.0) automatically retargets 3I + 3J as well. No provider-specific code in either feature.
+
+**Tested provider**: `claude-sdk` (the "B1" test path). The `offline-gemma4` test path (B4) — stress-test of prompt design against a small-context local model — is deferred to a follow-up session; the deferral and its acceptance criteria are documented in the (gitignored) project `BACKLOG.md`.
+
+#### Performance budget held
+
+All new code runs detached, on long timers, or at startup-only. Steady-state cost: zero. The startup analyzer (3I) only runs if unanalyzed bundles exist — typically 0 on a healthy run. The trends collector (3J) runs once every 24 h with a 60 s warmup after startup.
+
+Measured on Apple Silicon (vs. 4.26.0 baseline):
+- RSS idle: **+0 MB** (modules loaded lazily via dynamic `import()`)
+- Cold-start ready: **unchanged** (both modules load post-startup, fire-and-forget)
+- 3I per-bundle latency on claude-sdk: ~9 s
+- 3J per-analysis latency on claude-sdk: ~10 s
+
+#### New env vars
+
+```
+ALVIN_DISABLE_SELF_DIAGNOSIS=true        # disable 3I
+ALVIN_DISABLE_TRENDS=true                # disable 3J
+ALVIN_TRENDS_INTERVAL_HOURS=24           # default
+ALVIN_TRENDS_AI_AFTER_DAYS=7             # min history before AI kicks in
+```
+
+(All Phase-1 env vars from 4.26.0 continue to work — `ALVIN_DISABLE_SELF_PRESERVATION=true` still kills everything.)
+
+#### Why a major version bump
+
+Semantically, the bot is now **closing a loop on itself**: it observes its own forensics, asks an AI to interpret them, and reports back. That's a conceptual line worth marking. Nothing breaks — existing users update with `npm install -g alvin-bot@latest` and the new behaviour just appears in their next failure analysis.
+
+#### Files added
+
+- `src/services/self-diagnosis.ts` — 3I startup analyzer + analyzeBundle()
+- `src/services/trends.ts` — 3J snapshot collector + analyzeTrends()
+- `src/index.ts` — two fire-and-forget dynamic imports after Pre-Flight
+
+## [4.26.0] — 2026-05-13
+
+### Self-Preservation Phase 1 — four new resilience features, zero hot-path cost
+
+Bot now **survives more failure modes** and **alerts you when it can't survive them**. All four features run event-driven or on low-frequency timers — no hot-path overhead, measured RSS +4 MB / cold-start +81 ms vs baseline on a real Apple Silicon Mac (within the +5 MB / +2000 ms tolerance budget).
+
+#### Pre-Flight Sanity Check at startup (feature 1A)
+
+In parallel at boot, the bot now checks: (1) Telegram `getMe`, (2) AI provider `isAvailable()` — provider-agnostic via the existing Provider interface, works equally for `claude-sdk` / `codex-cli` / `groq` / `gemini` / `offline-gemma4` / etc., (3) SQLite `PRAGMA quick_check` on the embeddings DB, (4) Disk space ≥ 1 GB. Fire-and-forget — startup is **not** delayed; results land ~1 s after `Alvin Bot started` with severity-tagged output:
+
+```
+🩺 ✅ Pre-Flight: all checks ok — 986ms total
+   ✓ telegram     bot=@AlvinMBAM4_bot (405ms)
+   ✓ ai-provider  claude-sdk reachable (922ms)
+   ✓ sqlite       embeddings DB integrity ok (43ms)
+   ✓ disk         53.28 GB free (37ms)
+```
+
+Per-check timeouts (3 s / 5 s / 10 s / 2 s) bound the cost. Critical findings will feed Phase 2's auto-diagnostic (already wired). Opt-out: `ALVIN_DISABLE_PREFLIGHT=true`.
+
+#### Critical-Event Cross-Channel Notify (feature 1D)
+
+When the bot hits a state it can't recover from on its own — watchdog crash-loop brake engaged, repeated Telegram 409s, all providers dead, disk critically low — it now alerts the operator through a **fallback chain that doesn't depend on the bot's own platform being healthy**:
+
+1. **`~/.alvin-bot/CRITICAL.log`** — durable audit trail, always written first. Plain text, dated, machine-readable.
+2. **macOS native notification** via `osascript` — visible immediately on the user's desktop.
+3. **Telegram DM to admin** via `curl` — synchronous in exit-imminent contexts so the alert lands before `process.exit()` kills any pending I/O.
+
+The synchronous-vs-detached distinction matters: detached child processes get killed by macOS+launchd before they finish their fork-and-exec when the parent exits within a few ms. The watchdog brake explicitly uses `blockTelegram: true` to spawnSync the curl POST and confirm the HTTP response code. Plain-text body (not Markdown) so shell-command `suggestedAction`s with `"`, `&&`, etc. don't trigger Telegram's `Bad Request: can't parse entities` error. Opt-out: `ALVIN_DISABLE_CRITICAL_NOTIFY=true`.
+
+#### Zombie Dead-Man-Switch (feature 2E)
+
+Bot writes a unix-timestamp heartbeat to `~/.alvin-bot/heartbeat.txt` every 60 s. A **separate, tiny launchd LaunchAgent** (`com.alvinbot.deadman`) wakes every 5 min and checks the heartbeat — if older than 10 min, the watcher fires `launchctl kickstart -k gui/$UID/com.alvinbot.app` to force-restart.
+
+Catches the failure mode the in-process watchdog **cannot** see: process is alive but frozen (event-loop deadlock, blocked I/O, native-binding hang). The in-process watchdog can't detect its own death — that's a contradiction in terms — so the external observer is the only architecturally sound solution.
+
+Threshold overridable for testing: `ALVIN_DEADMAN_THRESHOLD_SEC=60` (default 600). End-to-end verified on a real Mac: `kill -STOP` froze the bot at PID X, watcher detected stale heartbeat 700 s old, kickstart fired, fresh PID Y came up within 8 s. CPU cost of the watcher: 0.017 %.
+
+#### Auto-Diagnostic Logs-Collector (feature 2F)
+
+On any critical failure, the bot now writes a structured forensic Markdown bundle to `~/.alvin-bot/diagnostics/<timestamp>-<category>.md` containing:
+
+1. Event detail + suggested action
+2. Process state (PID, RSS, heap, uptime, node version, platform, argv)
+3. Non-secret environment vars (PATH, PRIMARY_PROVIDER, FALLBACK_PROVIDERS, WEB_*, …)
+4. Last 200 lines of `alvin-bot.err.log`
+5. Last 200 lines of `alvin-bot.out.log`
+6. Watchdog state (`~/.alvin-bot/state/watchdog.json`)
+7. System tool inventory (`node`, `npm`, `brew`, `pm2`, `codex`, `claude`, `yt-dlp`, `ffmpeg`, `wacli`, `agent-browser`)
+8. Disk space (`df -h ~/.alvin-bot`)
+9. PM2 status (if PM2 installed — the same kind of state that bit us in 4.25.1)
+
+Bundles are ~18 KB each, capped at 50 retained files (oldest pruned automatically). The Telegram DM from feature 1D now includes the bundle path so the operator can immediately `cat` or scp it.
+
+This is also the data input the 5.0.0 AI-Self-Diagnosis (feature 3I) will feed to a sub-agent for automated analysis. As a 4.26.0 deliverable it stands on its own as "human-readable forensic dump".
+
+Opt-out: `ALVIN_DISABLE_AUTO_DIAGNOSTIC=true`.
+
+### Bundle wacli (WhatsApp CLI) with conditional opt-in
+
+`wacli` (https://wacli.sh, brew tap `steipete/tap`, v0.8.1, ~25 MB Go binary) is now part of `BOOTSTRAP_TOOLS` — but with a **hybrid install condition** that avoids forcing it onto users who don't use WhatsApp:
+
+- **If `wacli` is already installed** → bootstrap runs `brew upgrade wacli` (treated like any other bundled tool).
+- **If `WHATSAPP_ENABLED=true` is set in `.env`** → bootstrap installs via `brew install steipete/tap/wacli`.
+- **Otherwise** → silent skip with dimmer `·` icon: `· wacli (WhatsApp CLI) skipped (not opted in)`.
+
+License: see https://wacli.sh — alvin-bot does not bundle wacli, only invokes the user's brew, the user remains the licensee. macOS only (no Linux build upstream; bootstrap skips on Linux automatically).
+
+### Opt-out env vars summary
+
+For users who want minimal footprint:
+
+```
+ALVIN_DISABLE_SELF_PRESERVATION=true   # skip ALL Phase-1 features
+ALVIN_DISABLE_PREFLIGHT=true           # skip Pre-Flight only
+ALVIN_DISABLE_CRITICAL_NOTIFY=true     # skip cross-channel notify
+ALVIN_DISABLE_DEAD_MAN=true            # skip heartbeat writer
+ALVIN_DISABLE_AUTO_DIAGNOSTIC=true     # skip diagnostic bundles
+ALVIN_DEADMAN_THRESHOLD_SEC=600        # tune dead-man threshold (default 10 min)
+```
+
+### Performance budget verified on real hardware
+
+End-to-end measurements on Apple Silicon Mac (.75 test box):
+
+| Metric | Baseline 4.25.1 | 4.26.0 | Δ | Tolerance |
+|---|---|---|---|---|
+| Cold-start ready (median, throttled) | 5023 ms | 5104 ms | +81 ms | +2000 ms |
+| Cold-start ready (unthrottled, 1st run) | 2189 ms | 2170 ms | -19 ms | +2000 ms |
+| RSS idle steady-state | ~102 MB | 106.4 MB | +4.4 MB | +5 MB |
+| CPU idle | 0.0 % | 0.0 % | 0 | +0.1 % |
+| Log dir growth | stable | stable | n/a | <1 KB/s |
+
+All five metrics within tolerance.
+
 ## [4.25.1] — 2026-05-13
 
 ### Fixed: `alvin-bot launchd install` now persists the PM2 cleanup

package/bin/cli.js

@@ -272,6 +272,24 @@ const BOOTSTRAP_TOOLS = [
     install: { macos: "brew install ffmpeg", linux: "sudo apt-get install -y ffmpeg" },
     upgrade: { macos: "brew upgrade ffmpeg", linux: "sudo apt-get install --only-upgrade -y ffmpeg" },
   },
+  {
+    // wacli — WhatsApp CLI from steipete/tap. Hybrid bootstrap: only
+    // install/upgrade if the user has already installed it (we
+    // respect their existing setup) or has explicitly opted in via
+    // WHATSAPP_ENABLED=true in .env. This avoids pulling a ~25 MB
+    // Go binary onto every public user's machine, including those
+    // who never touch WhatsApp.
+    cmd: "wacli",
+    name: "wacli (WhatsApp CLI)",
+    license: "see https://wacli.sh — installed via your own brew, you remain the licensee",
+    install: { macos: "brew install steipete/tap/wacli", linux: null },
+    upgrade: { macos: "brew upgrade wacli", linux: null },
+    // Hybrid: only bootstrap if the user has explicitly signalled
+    // interest. installCondition is checked BEFORE any install/upgrade
+    // attempt; returns false → tool silently skipped.
+    installCondition: (env) =>
+      hasCommand("wacli") || env.WHATSAPP_ENABLED === "true",
+  },
 ];
 
 // Memoized: `brew update` is slow (5-30s) but needs to run at least once
@@ -309,6 +327,22 @@ function detectPlatformPm() {
 function bootstrapOneTool(tool, platform) {
   const cmdAvailable = hasCommand(tool.cmd);
 
+  // installCondition: optional gate that respects user intent. A tool with
+  // installCondition returning false is treated as "user hasn't opted in,
+  // silently skip". This is how wacli avoids forcing a 25 MB WhatsApp CLI
+  // onto every public user — only installs if they have it already or
+  // explicitly set WHATSAPP_ENABLED=true in .env.
+  if (typeof tool.installCondition === "function") {
+    try {
+      if (!tool.installCondition(process.env)) {
+        return { ok: true, skipped: true, message: `${tool.name} skipped (not opted in)` };
+      }
+    } catch {
+      // condition function threw — be defensive, skip
+      return { ok: true, skipped: true, message: `${tool.name} skipped (condition error)` };
+    }
+  }
+
   // Linux-only prerequisite check (e.g. pipx for yt-dlp).
   if (platform === "linux" && tool.linuxSkipIf && !hasCommand(tool.linuxSkipIf)) {
     return { ok: false, message: `${tool.name} skipped — needs '${tool.linuxSkipIf}' on Linux` };
@@ -376,12 +410,12 @@ async function ensureBootstrapTools(opts = {}) {
   const platform = detectPlatformPm();
   if (!platform) return;
 
-  console.log("\n🎬 Setting up media tools (yt-dlp + ffmpeg)...");
+  console.log("\n🎬 Setting up bundled tools (yt-dlp, ffmpeg, wacli on opt-in)...");
 
   // macOS needs brew on PATH — same trick as ensureBrewOnPath() uses.
   if (platform === "macos" && !hasCommand("brew")) {
     if (!ensureBrewOnPath()) {
-      console.log("  ⚠️  Skipping media-tool bootstrap — Homebrew not installed.");
+      console.log("  ⚠️  Skipping tool bootstrap — Homebrew not installed.");
       console.log("      To enable: install brew from https://brew.sh and re-run setup.");
       return;
     }
@@ -389,7 +423,9 @@ async function ensureBootstrapTools(opts = {}) {
 
   for (const tool of BOOTSTRAP_TOOLS) {
     const result = bootstrapOneTool(tool, platform);
-    console.log(`  ${result.ok ? "✓" : "⚠"} ${result.message}`);
+    // skipped (opt-in not signaled) → use dimmer icon, less attention-grabbing
+    const icon = result.skipped ? "·" : result.ok ? "✓" : "⚠";
+    console.log(`  ${icon} ${result.message}`);
   }
   console.log("");
 }
@@ -2688,7 +2724,80 @@ function launchdPaths() {
   const entryPoint = resolve(join(import.meta.dirname, "..", "dist", "index.js"));
   const cwd = resolve(join(import.meta.dirname, ".."));
   const nodePath = process.execPath;
-  return { home, label, plistPath, logDir, entryPoint, cwd, nodePath };
+  // Dead-man-switch watcher (Self-Preservation Phase 1, feature 2E).
+  // Separate, tiny LaunchAgent that fires every 5 min and force-restarts
+  // the main bot if its heartbeat-file is stale. The two agents are
+  // intentionally independent: if the main bot is wedged, the dead-man
+  // agent is still scheduling and reading the file.
+  const deadmanLabel = "com.alvinbot.deadman";
+  const deadmanPlistPath = join(home, "Library", "LaunchAgents", `${deadmanLabel}.plist`);
+  return { home, label, plistPath, logDir, entryPoint, cwd, nodePath, deadmanLabel, deadmanPlistPath };
+}
+
+/**
+ * Generate the dead-man watcher LaunchAgent plist. It runs a tiny shell
+ * script every 5 minutes (StartInterval) that compares the bot's
+ * heartbeat-file timestamp against now. If the heartbeat is more than
+ * 10 minutes stale, it `launchctl kickstart -k`s the main bot.
+ *
+ * The threshold is overridable via ALVIN_DEADMAN_THRESHOLD_SEC for
+ * testing; default is 600 s = 10 minutes.
+ *
+ * Why inline shell instead of a bundled script:
+ *   - Zero extra files to ship via npm
+ *   - Trivial to audit: 12 lines of POSIX sh
+ *   - No PATH dependency (uses absolute /bin paths)
+ */
+function renderDeadmanPlist({ deadmanLabel, mainLabel, home, logDir }) {
+  // Inline shell — kept POSIX-clean, uses only built-ins + launchctl.
+  // The redirect to logDir/deadman.log gives us a record of any
+  // kickstart actions without the watcher writing more than ~50
+  // bytes per event.
+  const script = `
+HEARTBEAT="${home}/.alvin-bot/heartbeat.txt"
+LOG="${logDir}/deadman.log"
+THRESHOLD="\${ALVIN_DEADMAN_THRESHOLD_SEC:-600}"
+if [ ! -f "$HEARTBEAT" ]; then exit 0; fi
+LAST=$(cat "$HEARTBEAT" 2>/dev/null | tr -d ' \\n')
+NOW=$(date +%s)
+case "$LAST" in
+  ''|*[!0-9]*) exit 0 ;;
+esac
+DIFF=$((NOW - LAST))
+if [ "$DIFF" -gt "$THRESHOLD" ]; then
+  echo "$(date -u +%FT%TZ) deadman: heartbeat $DIFF s old (> $THRESHOLD s), kickstarting ${mainLabel}" >> "$LOG"
+  /bin/launchctl kickstart -k "gui/$(id -u)/${mainLabel}" 2>>"$LOG" || true
+fi
+`.trim();
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>${deadmanLabel}</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>/bin/sh</string>
+        <string>-c</string>
+        <string>${script.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")}</string>
+    </array>
+
+    <key>StartInterval</key>
+    <integer>300</integer>
+
+    <key>RunAtLoad</key>
+    <false/>
+
+    <key>StandardErrorPath</key>
+    <string>${logDir}/deadman.err.log</string>
+
+    <key>LimitLoadToSessionType</key>
+    <string>Aqua</string>
+</dict>
+</plist>
+`;
 }
 
 async function launchdInstall() {
@@ -2830,6 +2939,38 @@ async function launchdInstall() {
     console.log(`   protected files. (Granted path: ${fda.realNodePath})`);
   }
 
+  // ── Dead-Man-Switch (Self-Preservation Phase 1, feature 2E) ──────────
+  // Install a second tiny LaunchAgent that wakes every 5 min and force-
+  // restarts the main bot if its heartbeat-file is stale. Catches "process
+  // alive but frozen" — event-loop deadlocks, blocked I/O, etc. — that
+  // the in-process watchdog can't see.
+  // Opt-out: ALVIN_DISABLE_DEAD_MAN=true or ALVIN_DISABLE_SELF_PRESERVATION=true.
+  if (
+    process.env.ALVIN_DISABLE_DEAD_MAN !== "true" &&
+    process.env.ALVIN_DISABLE_SELF_PRESERVATION !== "true"
+  ) {
+    const { deadmanLabel, deadmanPlistPath } = launchdPaths();
+    const deadmanPlist = renderDeadmanPlist({
+      deadmanLabel,
+      mainLabel: label,
+      home,
+      logDir,
+    });
+    writeFileSync(deadmanPlistPath, deadmanPlist, { mode: 0o644 });
+    console.log("");
+    console.log(`📝 Wrote ${deadmanPlistPath}`);
+    try {
+      execSync(`launchctl bootout gui/$(id -u)/${deadmanLabel} 2>/dev/null || true`, { stdio: "pipe" });
+    } catch {}
+    try {
+      execSync(`launchctl bootstrap gui/$(id -u) "${deadmanPlistPath}"`, { stdio: "pipe" });
+      console.log("🛡️  Dead-man watcher active — checks every 5 min, force-restarts main bot if heartbeat > 10 min stale.");
+    } catch (err) {
+      console.log(`⚠️  Dead-man watcher load failed (non-fatal): ${err.message?.split("\n")[0] || err}`);
+      console.log("   The main bot still works; only zombie-detection is disabled.");
+    }
+  }
+
   process.exit(0);
 }
 
@@ -2859,6 +3000,20 @@ async function launchdUninstall() {
     console.log(`⚠️  Could not remove plist: ${err.message}`);
   }
 
+  // Dead-Man watcher (feature 2E) — also remove its companion plist.
+  const { deadmanLabel, deadmanPlistPath } = launchdPaths();
+  if (existsSync(deadmanPlistPath)) {
+    try {
+      execSync(`launchctl bootout gui/$(id -u)/${deadmanLabel} 2>/dev/null || true`, { stdio: "pipe" });
+    } catch {}
+    try {
+      execSync(`rm -f "${deadmanPlistPath}"`);
+      console.log(`🗑  Removed ${deadmanPlistPath} (dead-man watcher)`);
+    } catch (err) {
+      console.log(`⚠️  Could not remove dead-man plist: ${err.message}`);
+    }
+  }
+
   console.log("");
   console.log("✅ alvin-bot is no longer a launchd user agent.");
   process.exit(0);

package/dist/index.js

@@ -204,6 +204,37 @@ if (hasProvider) {
 else {
     console.warn("⚠️  Engine not initialized — no AI provider configured.");
 }
+// Pre-Flight Sanity Check (Self-Preservation Phase 1, feature 1A) —
+// runs in parallel, fire-and-forget. Does NOT block startup.
+// Catches misconfigurations + degraded state at boot time.
+import("./services/preflight.js")
+    .then(({ runPreFlight, formatPreFlightReport }) => runPreFlight(config.botToken, registry).then((report) => {
+    console.log(formatPreFlightReport(report));
+}))
+    .catch((err) => {
+    // Pre-Flight itself must never crash the bot.
+    console.warn("⚠️  Pre-Flight check threw:", err?.message || err);
+});
+// AI Self-Diagnosis startup analyzer (Self-Preservation Phase 2, 3I).
+// Scans ~/.alvin-bot/diagnostics/ for forensic bundles without a
+// .analysis.md sidecar and runs AI analysis on each. Findings land on
+// the operator's phone via 1D Telegram channel within ~30 s of the
+// bot recovering from a brake. Fire-and-forget, never blocks startup.
+// Provider-agnostic: uses the active Provider's query() async generator.
+import("./services/self-diagnosis.js")
+    .then(({ runStartupAnalyzer }) => runStartupAnalyzer(registry))
+    .catch((err) => {
+    console.warn("⚠️  Self-diagnosis analyzer threw:", err?.message || err);
+});
+// Predictive-Maintenance Trends collector (Self-Preservation Phase 2, 3J).
+// Snapshots health metrics every 24 h (first one after 60 s warmup).
+// After 7 days of data, also runs AI anomaly detection daily.
+// If a concerning trend is flagged → DM operator via 1D channel.
+import("./services/trends.js")
+    .then(({ startTrendsCollector }) => startTrendsCollector(registry))
+    .catch((err) => {
+    console.warn("⚠️  Trends collector threw:", err?.message || err);
+});
 // Load plugins
 const pluginResult = await loadPlugins();
 if (pluginResult.loaded.length > 0) {
@@ -527,6 +558,14 @@ setNotifyCallback(async (target, text) => {
     enqueue(target.platform, String(target.chatId), text);
 });
 startScheduler();
+// Heartbeat-file writer (Self-Preservation Phase 1, feature 2E).
+// Writes ~/.alvin-bot/heartbeat.txt every 60 s so an external
+// dead-man-watch launchd agent can detect "process alive but frozen"
+// and force-restart the bot. Catches event-loop deadlocks that the
+// in-process watchdog cannot see.
+import("./services/heartbeat-file.js").then(({ startHeartbeatWriter }) => {
+    startHeartbeatWriter();
+});
 // Start the async-agent watcher (Fix #17 Stage 2). Polls outputFiles
 // of background sub-agents Claude launched with run_in_background and
 // delivers their completed reports as separate Telegram messages.

package/dist/services/auto-diagnostic.js

@@ -0,0 +1,228 @@
+/**
+ * Auto-Diagnostic Logs-Collector (Self-Preservation Phase 1, feature 2F).
+ *
+ * On critical failure, write a structured Markdown "forensic bundle" to
+ * ~/.alvin-bot/diagnostics/<timestamp>-<category>.md containing:
+ *
+ *   - Bot version + boot info
+ *   - Last 200 lines of out.log + err.log
+ *   - Current process state (PID, RSS, uptime, node version, platform)
+ *   - Non-secret environment vars (PATH, PRIMARY_PROVIDER, …)
+ *   - Watchdog state (~/.alvin-bot/state/watchdog.json)
+ *   - System tool inventory (which node/codex/claude/pm2/yt-dlp/…)
+ *   - Disk space snapshot
+ *   - The triggering event itself + suggestion
+ *
+ * The bundle is the input that the 5.0.0 AI-Diagnostic feature (3I) will
+ * later feed to a sub-agent for automated analysis. As of 4.26.0 it's a
+ * "human-readable forensic dump" — useful on its own, no AI required.
+ *
+ * Auto-prune: max 50 retained bundles, oldest deleted on next write.
+ *
+ * Performance: <100KB per bundle, ~50-200ms wall-clock per write,
+ * synchronous (we're typically called right before process.exit so
+ * blocking is the right semantic). Files are atomic — full bundle or
+ * nothing.
+ *
+ * Opt-out:
+ *   ALVIN_DISABLE_AUTO_DIAGNOSTIC=true        → skip bundle writes
+ *   ALVIN_DISABLE_SELF_PRESERVATION=true      → skip ALL Phase-1
+ */
+import { writeFileSync, readFileSync, mkdirSync, existsSync, readdirSync, statSync, unlinkSync, } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { execSync } from "child_process";
+import { BOT_VERSION } from "../version.js";
+const MAX_BUNDLES = 50;
+function isDisabled() {
+    return (process.env.ALVIN_DISABLE_AUTO_DIAGNOSTIC === "true" ||
+        process.env.ALVIN_DISABLE_SELF_PRESERVATION === "true");
+}
+function safeReadTail(filename, n) {
+    try {
+        const path = join(homedir(), ".alvin-bot", "logs", filename);
+        if (!existsSync(path))
+            return "(log file not present)";
+        const content = readFileSync(path, "utf-8");
+        const lines = content.split("\n");
+        return lines.slice(Math.max(0, lines.length - n)).join("\n");
+    }
+    catch (err) {
+        return `(read failed: ${err instanceof Error ? err.message : String(err)})`;
+    }
+}
+function safeShell(cmd, timeoutMs = 5000) {
+    try {
+        return execSync(cmd, { encoding: "utf-8", timeout: timeoutMs, stdio: ["ignore", "pipe", "pipe"] }).trim();
+    }
+    catch (err) {
+        const e = err;
+        const out = e.stdout?.toString().trim() ?? "";
+        const stderr = e.stderr?.toString().trim() ?? "";
+        if (out)
+            return out + (stderr ? `\n[stderr]: ${stderr}` : "");
+        return `(command failed: ${e.message || "unknown"})`;
+    }
+}
+function safeReadFile(path) {
+    try {
+        return readFileSync(path, "utf-8").trim();
+    }
+    catch (err) {
+        return `(could not read ${path}: ${err instanceof Error ? err.message : String(err)})`;
+    }
+}
+/**
+ * Prune diagnostic bundles older than MAX_BUNDLES (50). Oldest deleted
+ * first by mtime. Best-effort: silent on errors.
+ */
+export function pruneDiagnostics(maxKeep = MAX_BUNDLES) {
+    try {
+        const dir = join(homedir(), ".alvin-bot", "diagnostics");
+        if (!existsSync(dir))
+            return;
+        const files = readdirSync(dir)
+            .filter((f) => f.endsWith(".md"))
+            .map((f) => {
+            try {
+                return { name: f, mtime: statSync(join(dir, f)).mtimeMs };
+            }
+            catch {
+                return { name: f, mtime: 0 };
+            }
+        })
+            .sort((a, b) => b.mtime - a.mtime);
+        for (const f of files.slice(maxKeep)) {
+            try {
+                unlinkSync(join(dir, f.name));
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+    }
+    catch {
+        /* never fail the caller */
+    }
+}
+/**
+ * Write a diagnostic bundle for the given event. Returns the absolute
+ * path to the written file, or null if disabled / failed.
+ *
+ * Safe to call from any context — never throws. Side-effects:
+ *   - Creates ~/.alvin-bot/diagnostics/ if absent
+ *   - Writes a single ~50-100KB markdown file
+ *   - Prunes to MAX_BUNDLES retained
+ */
+export function writeDiagnosticBundle(event) {
+    if (isDisabled())
+        return null;
+    try {
+        const dir = join(homedir(), ".alvin-bot", "diagnostics");
+        mkdirSync(dir, { recursive: true });
+        const ts = (event.ts || new Date()).toISOString().replace(/[:.]/g, "-");
+        const filename = `${ts}-${event.category}.md`;
+        const filepath = join(dir, filename);
+        const mem = process.memoryUsage();
+        const rssMB = Math.round(mem.rss / 1024 / 1024);
+        const heapMB = Math.round(mem.heapUsed / 1024 / 1024);
+        const sections = [
+            `# Alvin Bot — Diagnostic Bundle`,
+            ``,
+            `**Generated:** ${new Date().toISOString()}`,
+            `**Bot version:** ${BOT_VERSION}`,
+            `**Trigger category:** ${event.category}`,
+            `**Severity:** ${event.severity}`,
+            `**Title:** ${event.title}`,
+            ``,
+            `## 1. Event Detail`,
+            ``,
+            "```",
+            event.detail,
+            "```",
+            ``,
+            ...(event.suggestedAction
+                ? [`### Suggested action`, ``, "```", event.suggestedAction, "```", ``]
+                : []),
+            `## 2. Process State`,
+            ``,
+            `- PID: ${process.pid}`,
+            `- RSS memory: ${rssMB} MB`,
+            `- Heap used: ${heapMB} MB`,
+            `- Uptime: ${Math.round(process.uptime())} s`,
+            `- Node.js: ${process.version}`,
+            `- Platform: ${process.platform} (${process.arch})`,
+            `- argv: ${process.argv.join(" ")}`,
+            ``,
+            `## 3. Environment (non-secret only)`,
+            ``,
+            ...[
+                "NODE_ENV",
+                "HOME",
+                "PATH",
+                "PRIMARY_PROVIDER",
+                "FALLBACK_PROVIDERS",
+                "AUTH_MODE",
+                "SESSION_MODE",
+                "WEB_HOST",
+                "WEB_PORT",
+                "WORKING_DIR",
+                "MAX_BUDGET_USD",
+                "ALVIN_DATA_DIR",
+                "ALVIN_DEADMAN_THRESHOLD_SEC",
+                "ALVIN_DISABLE_SELF_PRESERVATION",
+            ].map((key) => `- ${key}: ${process.env[key] ?? "(unset)"}`),
+            ``,
+            `## 4. Recent stderr (last 200 lines)`,
+            ``,
+            "```",
+            safeReadTail("alvin-bot.err.log", 200),
+            "```",
+            ``,
+            `## 5. Recent stdout (last 200 lines)`,
+            ``,
+            "```",
+            safeReadTail("alvin-bot.out.log", 200),
+            "```",
+            ``,
+            `## 6. Watchdog state`,
+            ``,
+            "```json",
+            safeReadFile(join(homedir(), ".alvin-bot", "state", "watchdog.json")),
+            "```",
+            ``,
+            `## 7. System tool inventory`,
+            ``,
+            "```",
+            safeShell("for t in node npm brew pm2 codex claude yt-dlp ffmpeg wacli agent-browser; do printf '%-15s %s\\n' \"$t\" \"$(command -v $t 2>/dev/null || echo NOT_FOUND)\"; done"),
+            "```",
+            ``,
+            `## 8. Disk space (.alvin-bot data dir)`,
+            ``,
+            "```",
+            safeShell(`df -h "${join(homedir(), ".alvin-bot")}" 2>&1 | head -2`),
+            "```",
+            ``,
+            `## 9. PM2 status (if installed)`,
+            ``,
+            "```",
+            safeShell("command -v pm2 >/dev/null && pm2 jlist 2>/dev/null | head -50 || echo 'pm2 not installed'", 3000),
+            "```",
+            ``,
+            `---`,
+            ``,
+            `*This bundle was generated automatically by the Alvin Bot auto-diagnostic system.*`,
+            `*Set \`ALVIN_DISABLE_AUTO_DIAGNOSTIC=true\` in ~/.alvin-bot/.env to opt out.*`,
+            ``,
+        ];
+        writeFileSync(filepath, sections.join("\n"), { mode: 0o600 });
+        pruneDiagnostics();
+        return filepath;
+    }
+    catch (err) {
+        // Diagnostic writer must not be a new failure mode. Log to stderr
+        // (which the critical-notify file flag will reference) and bail.
+        console.error(`[auto-diagnostic] failed to write bundle: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}