@inetafrica/open-claudia 1.7.1 → 1.7.3

package/Dockerfile

@@ -11,6 +11,9 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 RUN curl -fsSL https://claude.ai/install.sh | sh || \
     npm install -g @anthropic-ai/claude-code
 
+# Create non-root user (Claude Code refuses --dangerously-skip-permissions as root)
+RUN groupadd -g 1000 claudia && useradd -u 1000 -g 1000 -m -d /data claudia
+
 # Create app directory
 WORKDIR /app
 
@@ -21,6 +24,14 @@ RUN npm ci --production
 # Copy app source
 COPY . .
 
+# Entrypoint auto-configures from env vars on first run
+COPY docker-entrypoint.sh /usr/local/bin/
+RUN chmod +x /usr/local/bin/docker-entrypoint.sh
+
+# Set up data directory ownership
+RUN mkdir -p /data/Workspace /data/.open-claudia /data/.claude && \
+    chown -R claudia:claudia /data
+
 # Config and data volume
 ENV HOME=/data
 ENV WEB_UI=true
@@ -29,10 +40,8 @@ VOLUME /data
 
 EXPOSE 8080
 
-# Entrypoint auto-configures from env vars on first run
-COPY docker-entrypoint.sh /usr/local/bin/
-RUN chmod +x /usr/local/bin/docker-entrypoint.sh
-ENTRYPOINT ["docker-entrypoint.sh"]
+# Switch to non-root user
+USER 1000
 
-# Start with web UI enabled
+ENTRYPOINT ["docker-entrypoint.sh"]
 CMD ["node", "bin/cli.js", "web"]

package/bin/cli.js

@@ -9,6 +9,7 @@ const command = args[0] || "help";
 
 const botDir = path.join(__dirname, "..");
 const configDir = require(path.join(botDir, "config-dir"));
+const health = require(path.join(botDir, "health"));
 
 function getBotFile() {
   const modeFile = path.join(configDir, ".bot-mode");
@@ -19,6 +20,15 @@ function getBotFile() {
   return "bot.js";
 }
 
+function startBot(botFile, args) {
+  // Start web UI alongside bot if WEB_UI=true or --web flag
+  if (process.env.WEB_UI === "true" || args.includes("--web")) {
+    const { startWebServer } = require(path.join(botDir, "web.js"));
+    startWebServer();
+  }
+  require(path.join(botDir, botFile));
+}
+
 function findBotProcesses() {
   try {
     if (process.platform === "win32") {
@@ -49,14 +59,42 @@ switch (command) {
     break;
 
   case "start": {
+    const skipHealthCheck = args.includes("--skip-health") || args.includes("--force");
     const botFile = getBotFile();
-    console.log(`Starting Open Claudia (${botFile === "bot-agent.js" ? "agent" : "direct"} mode)...`);
-    // Start web UI alongside bot if WEB_UI=true or --web flag
-    if (process.env.WEB_UI === "true" || args.includes("--web")) {
-      const { startWebServer } = require(path.join(botDir, "web.js"));
-      startWebServer();
+
+    // Run health checks before starting (unless skipped)
+    if (!skipHealthCheck) {
+      console.log("Running health checks...");
+      health.runHealthChecks({ quick: args.includes("--quick") }).then((results) => {
+        if (!results.ok) {
+          console.error("\n" + health.formatResults(results, true));
+          console.error("\nFix the issues above or use --skip-health to bypass (not recommended).");
+          process.exit(1);
+        }
+        if (results.warnings.length > 0) {
+          console.log("Warnings:");
+          for (const w of results.warnings) console.log(`  - ${w}`);
+        }
+        console.log(`Starting Open Claudia (${botFile === "bot-agent.js" ? "agent" : "direct"} mode)...`);
+        startBot(botFile, args);
+      }).catch((err) => {
+        console.error("Health check failed:", err.message);
+        process.exit(1);
+      });
+    } else {
+      console.log(`Starting Open Claudia (${botFile === "bot-agent.js" ? "agent" : "direct"} mode)...`);
+      startBot(botFile, args);
     }
-    require(path.join(botDir, botFile));
+    break;
+  }
+
+  case "health": {
+    console.log("Running health checks...\n");
+    const verbose = args.includes("-v") || args.includes("--verbose");
+    health.runHealthChecks({ quick: false }).then((results) => {
+      console.log(health.formatResults(results, verbose));
+      process.exit(results.ok ? 0 : 1);
+    });
     break;
   }
 
@@ -123,6 +161,15 @@ Commands:
   open-claudia web      Start with web UI for setup/config
   open-claudia stop     Stop the bot
   open-claudia status   Check if running
+  open-claudia health   Run environment health checks
   open-claudia logs     View recent logs
+
+Start options:
+  --web           Also start the web UI
+  --quick         Skip slow health checks (Claude auth, Telegram API)
+  --skip-health   Bypass all health checks (not recommended)
+
+Health options:
+  -v, --verbose   Show detailed check results
 `);
 }

package/bot-agent.js

@@ -1018,10 +1018,11 @@ bot.onText(/\/upgrade$/, async (msg) => {
   try {
     execSync("npm install -g @inetafrica/open-claudia@latest 2>&1", {
       encoding: "utf-8", timeout: 120000,
+      cwd: process.env.HOME || require("os").homedir(),
       env: { ...process.env, PATH: FULL_PATH, HOME: process.env.HOME || require("os").homedir() },
     });
     // Read version from newly installed package
-    const root = execSync("npm root -g", { encoding: "utf-8", env: { ...process.env, PATH: FULL_PATH } }).trim();
+    const root = execSync("npm root -g", { encoding: "utf-8", cwd: process.env.HOME || require("os").homedir(), env: { ...process.env, PATH: FULL_PATH } }).trim();
     const newPkg = JSON.parse(fs.readFileSync(path.join(root, "@inetafrica", "open-claudia", "package.json"), "utf-8"));
     await send(`Installed v${newPkg.version}. Going offline to restart...`);
   } catch (e) {

package/bot.js

@@ -8,8 +8,39 @@ const Vault = require("./vault");
 const CONFIG_DIR = require("./config-dir");
 
 // ── Graceful shutdown & error handling ─────────────────────────────
-process.on("SIGINT", () => process.exit(0));
-process.on("SIGTERM", () => process.exit(0));
+async function gracefulShutdown(signal) {
+  console.log(`Received ${signal}, shutting down gracefully...`);
+  // Stop any running Claude process
+  if (typeof runningProcess !== "undefined" && runningProcess) {
+    try {
+      process.kill(-runningProcess.pid, "SIGTERM");
+    } catch (e) {
+      try { runningProcess.kill("SIGTERM"); } catch (e2) {}
+    }
+  }
+  // Clean up temp media files older than 1 hour
+  try {
+    const CONFIG_DIR_TEMP = require("./config-dir");
+    const mediaDir = require("path").join(CONFIG_DIR_TEMP, "media");
+    if (require("fs").existsSync(mediaDir)) {
+      const files = require("fs").readdirSync(mediaDir);
+      const oneHourAgo = Date.now() - 60 * 60 * 1000;
+      for (const file of files) {
+        const filePath = require("path").join(mediaDir, file);
+        try {
+          const stat = require("fs").statSync(filePath);
+          if (stat.mtimeMs < oneHourAgo) {
+            require("fs").unlinkSync(filePath);
+          }
+        } catch (e) {}
+      }
+    }
+  } catch (e) {}
+  process.exit(0);
+}
+
+process.on("SIGINT", () => gracefulShutdown("SIGINT"));
+process.on("SIGTERM", () => gracefulShutdown("SIGTERM"));
 
 // Notify user of crashes via Telegram before exiting
 function notifyError(label, err) {
@@ -76,6 +107,34 @@ const CHAT_IDS = (config.TELEGRAM_CHAT_ID || "").split(",").map((s) => s.trim())
 const CHAT_ID = CHAT_IDS[0]; // Primary owner chat for crons/notifications
 const WORKSPACE = config.WORKSPACE;
 const CLAUDE_PATH = config.CLAUDE_PATH;
+
+// Validate critical config at startup
+if (!TOKEN) { console.error("TELEGRAM_BOT_TOKEN not set"); process.exit(1); }
+if (!CHAT_ID) { console.error("TELEGRAM_CHAT_ID not set"); process.exit(1); }
+if (!WORKSPACE) { console.error("WORKSPACE not set"); process.exit(1); }
+if (!CLAUDE_PATH) { console.error("CLAUDE_PATH not set"); process.exit(1); }
+
+// Ensure workspace exists
+if (!fs.existsSync(WORKSPACE)) {
+  try {
+    fs.mkdirSync(WORKSPACE, { recursive: true });
+    console.log(`Created workspace: ${WORKSPACE}`);
+  } catch (e) {
+    console.error(`Failed to create workspace: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+// Verify Claude CLI exists
+if (!fs.existsSync(CLAUDE_PATH)) {
+  const { execSync } = require("child_process");
+  try {
+    execSync(`which "${CLAUDE_PATH}" 2>/dev/null || where "${CLAUDE_PATH}" 2>nul`, { encoding: "utf-8" });
+  } catch (e) {
+    console.error(`Claude CLI not found at: ${CLAUDE_PATH}`);
+    process.exit(1);
+  }
+}
 const WHISPER_CLI = config.WHISPER_CLI || "";
 const WHISPER_MODEL = config.WHISPER_MODEL || "";
 const FFMPEG = config.FFMPEG || "";
@@ -188,6 +247,13 @@ const FILES_DIR = path.join(CONFIG_DIR, "files");
 if (!fs.existsSync(TEMP_DIR)) fs.mkdirSync(TEMP_DIR, { recursive: true });
 if (!fs.existsSync(FILES_DIR)) fs.mkdirSync(FILES_DIR, { recursive: true });
 
+// File size limits (in bytes)
+const MAX_FILE_SIZE = 50 * 1024 * 1024; // 50MB max for documents
+const MAX_VOICE_SIZE = 10 * 1024 * 1024; // 10MB max for voice/audio
+
+// Process timeout (30 minutes max)
+const MAX_PROCESS_TIMEOUT = 30 * 60 * 1000;
+
 // ── Persistent state ───────────────────────────────────────────────
 const STATE_FILE = path.join(CONFIG_DIR, "state.json");
 const SESSIONS_FILE = path.join(CONFIG_DIR, "sessions.json");
@@ -695,6 +761,21 @@ async function runClaude(prompt, cwd, replyToMsgId, opts = {}) {
   const startTime = Date.now();
   let longRunningNotified = false;
 
+  // Hard timeout to prevent runaway processes
+  const processTimeout = setTimeout(async () => {
+    if (runningProcess === proc) {
+      try {
+        process.kill(-proc.pid, "SIGTERM");
+        setTimeout(() => {
+          try { process.kill(-proc.pid, "SIGKILL"); } catch (e) {}
+        }, 5000);
+      } catch (e) {
+        try { proc.kill("SIGKILL"); } catch (e2) {}
+      }
+      await send(`Task timed out after ${MAX_PROCESS_TIMEOUT / 60000} minutes. Stopped.`);
+    }
+  }, MAX_PROCESS_TIMEOUT);
+
   let lastUpdate = "";
   // Adaptive update interval: 2s for first 2min, then 5s to avoid rate limits
   const scheduleUpdate = () => {
@@ -756,11 +837,26 @@ async function runClaude(prompt, cwd, replyToMsgId, opts = {}) {
     }
   });
 
-  proc.stderr.on("data", (d) => console.error("STDERR:", d.toString()));
+  let stderrBuffer = "";
+  proc.stderr.on("data", (d) => {
+    const chunk = d.toString();
+    stderrBuffer += chunk;
+    console.error("STDERR:", chunk);
+  });
 
   proc.on("close", async (code) => {
     runningProcess = null;
     clearTimeout(streamInterval); streamInterval = null;
+    clearTimeout(processTimeout);
+
+    // Check for auth errors in stderr
+    const stderrLower = stderrBuffer.toLowerCase();
+    if (stderrLower.includes("unauthorized") || stderrLower.includes("auth") && stderrLower.includes("fail") ||
+        stderrLower.includes("api key") || stderrLower.includes("not logged in")) {
+      await send("Claude authentication error. Run `claude auth` to re-authenticate.");
+      return;
+    }
+
     try {
       const finalText = assistantText || "(no output)";
       const chunks = splitMessage(finalText);
@@ -805,8 +901,11 @@ async function runClaude(prompt, cwd, replyToMsgId, opts = {}) {
   });
 
   proc.on("error", async (err) => {
-    runningProcess = null; clearTimeout(streamInterval);
-    await send(`Error: ${err.message}`); statusMessageId = null;
+    runningProcess = null;
+    clearTimeout(streamInterval);
+    clearTimeout(processTimeout);
+    await send(`Error: ${err.message}`);
+    statusMessageId = null;
   });
 }
 
@@ -959,10 +1058,11 @@ bot.onText(/\/upgrade$/, async (msg) => {
   try {
     execSync("npm install -g @inetafrica/open-claudia@latest 2>&1", {
       encoding: "utf-8", timeout: 120000,
+      cwd: process.env.HOME || require("os").homedir(),
       env: { ...process.env, PATH: FULL_PATH, HOME: process.env.HOME || require("os").homedir() },
     });
     // Read version from newly installed package
-    const root = execSync("npm root -g", { encoding: "utf-8", env: { ...process.env, PATH: FULL_PATH } }).trim();
+    const root = execSync("npm root -g", { encoding: "utf-8", cwd: process.env.HOME || require("os").homedir(), env: { ...process.env, PATH: FULL_PATH } }).trim();
     const newPkg = JSON.parse(fs.readFileSync(path.join(root, "@inetafrica", "open-claudia", "package.json"), "utf-8"));
     await send(`Installed v${newPkg.version}. Going offline to restart...`);
   } catch (e) {
@@ -1241,6 +1341,10 @@ bot.on("voice", async (msg) => {
   if (!isAuthorized(msg)) return;
   if (!requireSession(msg)) return;
   try {
+    // Check file size
+    if (msg.voice.file_size && msg.voice.file_size > MAX_VOICE_SIZE) {
+      return send(`Voice note too large (${Math.round(msg.voice.file_size / 1024 / 1024)}MB). Max: ${MAX_VOICE_SIZE / 1024 / 1024}MB`);
+    }
     bot.sendChatAction(CHAT_ID, "typing");
     const oggPath = await downloadFile(msg.voice.file_id, ".ogg");
     const transcript = transcribeAudio(oggPath);
@@ -1282,6 +1386,10 @@ bot.on("document", async (msg) => {
   if (!isAuthorized(msg)) return;
   if (!requireSession(msg)) return;
   try {
+    // Check file size
+    if (msg.document.file_size && msg.document.file_size > MAX_FILE_SIZE) {
+      return send(`File too large (${Math.round(msg.document.file_size / 1024 / 1024)}MB). Max: ${MAX_FILE_SIZE / 1024 / 1024}MB`);
+    }
     const fileName = msg.document.file_name || `file-${Date.now()}`;
     const mime = msg.document.mime_type || "";
     // Save with original name to files dir

package/health.js

@@ -0,0 +1,391 @@
+const { execSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+const https = require("https");
+const CONFIG_DIR = require("./config-dir");
+
+const ENV_FILE = path.join(CONFIG_DIR, ".env");
+const AUTH_FILE = path.join(CONFIG_DIR, "auth.json");
+
+// Required env keys for the bot to function
+const REQUIRED_ENV_KEYS = [
+  "TELEGRAM_BOT_TOKEN",
+  "TELEGRAM_CHAT_ID",
+  "WORKSPACE",
+  "CLAUDE_PATH",
+];
+
+// Optional but recommended
+const OPTIONAL_ENV_KEYS = [
+  "WHISPER_CLI",
+  "WHISPER_MODEL",
+  "FFMPEG",
+  "VAULT_FILE",
+  "SOUL_FILE",
+  "CRONS_FILE",
+];
+
+/**
+ * Load and parse .env file
+ */
+function loadEnv() {
+  if (!fs.existsSync(ENV_FILE)) return null;
+  const lines = fs.readFileSync(ENV_FILE, "utf-8").split("\n");
+  const env = {};
+  for (const line of lines) {
+    const idx = line.indexOf("=");
+    if (idx > 0) env[line.slice(0, idx).trim()] = line.slice(idx + 1).trim();
+  }
+  return env;
+}
+
+/**
+ * Check if a binary exists at the given path
+ */
+function binaryExists(binPath) {
+  if (!binPath) return false;
+  try {
+    fs.accessSync(binPath, fs.constants.X_OK);
+    return true;
+  } catch (e) {
+    // Try which/where as fallback
+    try {
+      const cmd = process.platform === "win32" ? `where "${binPath}"` : `which "${binPath}"`;
+      execSync(cmd, { encoding: "utf-8", stdio: "pipe" });
+      return true;
+    } catch (e2) {
+      return false;
+    }
+  }
+}
+
+/**
+ * Test if Claude CLI is authenticated
+ */
+function testClaudeAuth(claudePath) {
+  try {
+    execSync(`"${claudePath}" -p "say ok" --max-budget-usd 0.01 --output-format text 2>&1`, {
+      encoding: "utf-8",
+      timeout: 30000,
+      stdio: "pipe",
+    });
+    return { ok: true };
+  } catch (e) {
+    const errMsg = (e.stderr || e.stdout || e.message || "").toLowerCase();
+    if (errMsg.includes("auth") || errMsg.includes("login") || errMsg.includes("api key") || errMsg.includes("unauthorized")) {
+      return { ok: false, reason: "not_authenticated", message: "Claude CLI is not authenticated. Run 'claude auth' or 'claude login'." };
+    }
+    // Other errors (like timeout) are OK - Claude is accessible
+    return { ok: true };
+  }
+}
+
+/**
+ * Test Telegram bot token validity
+ */
+function testTelegramToken(token) {
+  return new Promise((resolve) => {
+    const timeout = setTimeout(() => resolve({ ok: false, reason: "timeout", message: "Telegram API request timed out" }), 15000);
+
+    https.get(`https://api.telegram.org/bot${token}/getMe`, (res) => {
+      let data = "";
+      res.on("data", (d) => { data += d; });
+      res.on("end", () => {
+        clearTimeout(timeout);
+        try {
+          const json = JSON.parse(data);
+          if (json.ok) {
+            resolve({ ok: true, botInfo: json.result });
+          } else {
+            resolve({ ok: false, reason: "invalid_token", message: `Telegram API error: ${json.description || "Invalid token"}` });
+          }
+        } catch (e) {
+          resolve({ ok: false, reason: "parse_error", message: "Failed to parse Telegram API response" });
+        }
+      });
+    }).on("error", (err) => {
+      clearTimeout(timeout);
+      resolve({ ok: false, reason: "network_error", message: `Network error: ${err.message}` });
+    });
+  });
+}
+
+/**
+ * Check if directory exists and is writable
+ */
+function checkDirectory(dirPath, createIfMissing = false) {
+  if (!dirPath) return { ok: false, reason: "not_configured", message: "Path not configured" };
+
+  if (!fs.existsSync(dirPath)) {
+    if (createIfMissing) {
+      try {
+        fs.mkdirSync(dirPath, { recursive: true });
+        return { ok: true, created: true };
+      } catch (e) {
+        return { ok: false, reason: "create_failed", message: `Failed to create directory: ${e.message}` };
+      }
+    }
+    return { ok: false, reason: "not_found", message: `Directory does not exist: ${dirPath}` };
+  }
+
+  // Check if writable
+  try {
+    const testFile = path.join(dirPath, `.write-test-${Date.now()}`);
+    fs.writeFileSync(testFile, "test");
+    fs.unlinkSync(testFile);
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, reason: "not_writable", message: `Directory is not writable: ${dirPath}` };
+  }
+}
+
+/**
+ * Check if Node.js version is compatible
+ */
+function checkNodeVersion() {
+  const version = process.version;
+  const major = parseInt(version.slice(1).split(".")[0], 10);
+  if (major < 18) {
+    return { ok: false, reason: "version_too_old", message: `Node.js ${version} is too old. Requires Node.js 18 or higher.`, version };
+  }
+  return { ok: true, version };
+}
+
+/**
+ * Check for conflicting bot instances
+ */
+function checkForConflictingProcesses() {
+  try {
+    let pids;
+    if (process.platform === "win32") {
+      const wmic = execSync('wmic process where "name=\'node.exe\'" get ProcessId,CommandLine /FORMAT:CSV 2>nul', { encoding: "utf-8" });
+      pids = [];
+      for (const line of wmic.split("\n")) {
+        if (line.includes("bot.js") && line.includes("open-claudia")) {
+          const parts = line.trim().split(",");
+          const pid = parts[parts.length - 1];
+          if (pid && pid !== String(process.pid)) pids.push(pid.trim());
+        }
+      }
+    } else {
+      const out = execSync('ps -eo pid,command | grep "bot\\(-agent\\)\\?\\.js" | grep "open-claudia" | grep -v grep 2>/dev/null || true', { encoding: "utf-8" });
+      pids = out.trim().split("\n")
+        .map((l) => l.trim().split(/\s+/)[0])
+        .filter((pid) => pid && pid !== String(process.pid));
+    }
+
+    if (pids.length > 0) {
+      return { ok: false, reason: "conflict", message: `Another instance is already running (PID: ${pids.join(", ")})`, pids };
+    }
+    return { ok: true };
+  } catch (e) {
+    // Can't detect - assume OK
+    return { ok: true };
+  }
+}
+
+/**
+ * Check available disk space
+ */
+function checkDiskSpace(dirPath) {
+  try {
+    if (process.platform === "win32") {
+      // Skip on Windows for now
+      return { ok: true, skipped: true };
+    }
+    const out = execSync(`df -k "${dirPath}" | tail -1`, { encoding: "utf-8" });
+    const parts = out.trim().split(/\s+/);
+    const availableKB = parseInt(parts[3], 10);
+    const availableMB = Math.floor(availableKB / 1024);
+
+    if (availableMB < 100) {
+      return { ok: false, reason: "low_space", message: `Low disk space: ${availableMB}MB available`, availableMB };
+    }
+    return { ok: true, availableMB };
+  } catch (e) {
+    return { ok: true, skipped: true };
+  }
+}
+
+/**
+ * Validate auth.json structure
+ */
+function checkAuthFile() {
+  if (!fs.existsSync(AUTH_FILE)) {
+    return { ok: true, exists: false };
+  }
+  try {
+    const auth = JSON.parse(fs.readFileSync(AUTH_FILE, "utf-8"));
+    if (!Array.isArray(auth.authorized)) {
+      return { ok: false, reason: "invalid_structure", message: "auth.json is malformed (missing authorized array)" };
+    }
+    return { ok: true, exists: true, authorizedCount: auth.authorized.length };
+  } catch (e) {
+    return { ok: false, reason: "parse_error", message: `Failed to parse auth.json: ${e.message}` };
+  }
+}
+
+/**
+ * Run all health checks
+ * @param {Object} options - Options
+ * @param {boolean} options.quick - Skip slow checks (Claude auth, Telegram API)
+ * @param {boolean} options.fix - Attempt to fix issues (create directories)
+ * @returns {Promise<Object>} Health check results
+ */
+async function runHealthChecks(options = {}) {
+  const { quick = false, fix = false } = options;
+  const results = {
+    ok: true,
+    checks: {},
+    errors: [],
+    warnings: [],
+  };
+
+  // 1. Check Node.js version
+  results.checks.node = checkNodeVersion();
+  if (!results.checks.node.ok) {
+    results.ok = false;
+    results.errors.push(results.checks.node.message);
+  }
+
+  // 2. Check .env file exists and has required keys
+  const env = loadEnv();
+  if (!env) {
+    results.checks.env = { ok: false, reason: "not_found", message: "No .env file found. Run 'open-claudia setup' first." };
+    results.ok = false;
+    results.errors.push(results.checks.env.message);
+    // Can't continue without env
+    return results;
+  }
+
+  const missingKeys = REQUIRED_ENV_KEYS.filter((k) => !env[k]);
+  if (missingKeys.length > 0) {
+    results.checks.env = { ok: false, reason: "missing_keys", message: `Missing required config: ${missingKeys.join(", ")}`, missingKeys };
+    results.ok = false;
+    results.errors.push(results.checks.env.message);
+  } else {
+    results.checks.env = { ok: true };
+  }
+
+  // 3. Check Claude CLI exists
+  const claudePath = env.CLAUDE_PATH;
+  if (!binaryExists(claudePath)) {
+    results.checks.claude_binary = { ok: false, reason: "not_found", message: `Claude CLI not found at: ${claudePath}` };
+    results.ok = false;
+    results.errors.push(results.checks.claude_binary.message);
+  } else {
+    results.checks.claude_binary = { ok: true, path: claudePath };
+
+    // 4. Check Claude authentication (slow)
+    if (!quick) {
+      results.checks.claude_auth = testClaudeAuth(claudePath);
+      if (!results.checks.claude_auth.ok) {
+        results.ok = false;
+        results.errors.push(results.checks.claude_auth.message);
+      }
+    }
+  }
+
+  // 5. Check Telegram token (slow)
+  if (!quick && env.TELEGRAM_BOT_TOKEN) {
+    results.checks.telegram = await testTelegramToken(env.TELEGRAM_BOT_TOKEN);
+    if (!results.checks.telegram.ok) {
+      results.ok = false;
+      results.errors.push(results.checks.telegram.message);
+    }
+  }
+
+  // 6. Check workspace directory
+  results.checks.workspace = checkDirectory(env.WORKSPACE, fix);
+  if (!results.checks.workspace.ok) {
+    results.ok = false;
+    results.errors.push(results.checks.workspace.message);
+  }
+
+  // 7. Check config directory
+  results.checks.config_dir = checkDirectory(CONFIG_DIR, fix);
+  if (!results.checks.config_dir.ok) {
+    results.ok = false;
+    results.errors.push(results.checks.config_dir.message);
+  }
+
+  // 8. Check for conflicting processes
+  results.checks.conflicts = checkForConflictingProcesses();
+  if (!results.checks.conflicts.ok) {
+    results.ok = false;
+    results.errors.push(results.checks.conflicts.message);
+  }
+
+  // 9. Check disk space
+  results.checks.disk = checkDiskSpace(CONFIG_DIR);
+  if (!results.checks.disk.ok) {
+    results.warnings.push(results.checks.disk.message);
+  }
+
+  // 10. Check auth.json
+  results.checks.auth_file = checkAuthFile();
+  if (!results.checks.auth_file.ok) {
+    results.warnings.push(results.checks.auth_file.message);
+  }
+
+  // 11. Check optional features
+  if (env.WHISPER_CLI && !binaryExists(env.WHISPER_CLI)) {
+    results.warnings.push(`Whisper CLI not found at: ${env.WHISPER_CLI} (voice notes disabled)`);
+  }
+  if (env.FFMPEG && !binaryExists(env.FFMPEG)) {
+    results.warnings.push(`FFmpeg not found at: ${env.FFMPEG} (voice notes disabled)`);
+  }
+
+  return results;
+}
+
+/**
+ * Format health check results for display
+ */
+function formatResults(results, verbose = false) {
+  const lines = [];
+
+  if (results.ok) {
+    lines.push("Health check passed.");
+  } else {
+    lines.push("Health check FAILED.");
+  }
+
+  if (results.errors.length > 0) {
+    lines.push("\nErrors:");
+    for (const err of results.errors) {
+      lines.push(`  - ${err}`);
+    }
+  }
+
+  if (results.warnings.length > 0) {
+    lines.push("\nWarnings:");
+    for (const warn of results.warnings) {
+      lines.push(`  - ${warn}`);
+    }
+  }
+
+  if (verbose) {
+    lines.push("\nDetails:");
+    for (const [name, check] of Object.entries(results.checks)) {
+      const status = check.ok ? "OK" : "FAIL";
+      lines.push(`  ${name}: ${status}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+module.exports = {
+  runHealthChecks,
+  formatResults,
+  loadEnv,
+  testClaudeAuth,
+  testTelegramToken,
+  checkDirectory,
+  checkNodeVersion,
+  checkForConflictingProcesses,
+  binaryExists,
+  REQUIRED_ENV_KEYS,
+  OPTIONAL_ENV_KEYS,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inetafrica/open-claudia",
-  "version": "1.7.1",
+  "version": "1.7.3",
   "description": "Your always-on AI coding assistant — Claude Code via Telegram",
   "main": "bot.js",
   "bin": {
@@ -15,6 +15,7 @@
     "bot.js",
     "bot-agent.js",
     "vault.js",
+    "health.js",
     "setup.js",
     "web.js",
     "config-dir.js",