@inetafrica/open-claudia 1.18.0 → 1.19.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## v1.19.0
+- Added `/doctor` / `/requirements`: mobile-friendly checks for Node.js, Claude/Cursor/Codex CLI versions and auth, optional ffmpeg/Whisper voice stack, workspace writability, and config dir writability
+- `/upgrade` now includes a post-upgrade requirements/auth summary before restarting, so missing CLIs or auth breakage is visible immediately
+- Added Codex auth commands: `/codex_auth_status`, `/codex_login` device auth, `/codex_setup_token` / `/codex_use_api_key` secure API-key paste mode, and `/cancel_codex_auth`
+- Codex/OpenAI keys are redacted from Telegram output/logs; API keys are passed to `codex login --with-api-key` without being echoed
+- Added canonical user identity links for future multi-channel support. State and session history now key by canonical user id (`telegram:<chatId>` by default, or an explicit id like `sumeet@inet.africa`) instead of raw Telegram chat id.
+- Added `/link`, `/links`, and `/whoami` for managing and inspecting Telegram-to-user mappings.
+- Existing `state.json` and `sessions.json` chat-id keys are migrated through the identity resolver on load.
+
 ## v1.18.0
 - Auto-compacts high-context sessions before the next turn (`AUTO_COMPACT_TOKENS`, default 140k): summarizes the old session, seeds a fresh session, then continues the user's request there
 - `/compact` now creates a fresh compacted continuation session instead of only adding another summary turn to the existing session

package/README.md

@@ -22,6 +22,7 @@ Send text, voice notes, screenshots, and files from your phone. Your chosen AI a
 - **Model switching** — toggle between models on either backend
 - **Plan mode, effort levels, budgets** — full control from Telegram
 - **Auto-updates** — checks for new versions every 5 minutes, upgrade with `/upgrade`
+- **Requirements doctor** — `/doctor` / `/requirements` checks CLI installs, auth, voice tools, and writable paths after upgrades
 - **Multi-user auth** — authorize additional users with code verification
 - **Cross-platform** — works on macOS, Linux, and Windows
 
@@ -60,6 +61,8 @@ agent status              # Verify: should show your email and plan
 ```bash
 npm install -g @openai/codex
 codex login               # Opens browser to authenticate
+# Or from Telegram after Open Claudia is running: /codex_login
+# If browser/device login cannot complete remotely: /codex_setup_token
 codex --version           # Verify it works
 ```
 
@@ -141,6 +144,7 @@ When you select a project, the last conversation is automatically resumed. Tap "
 | `/worktree` | Toggle isolated git branch — Claude only |
 | `/mode` | Switch between direct and agent bot modes |
 | `/status` | Show current session, backend, and settings |
+| `/doctor` / `/requirements` | Check Node, CLI binaries/versions/auth, voice stack, and writable paths |
 
 ### Automation
 
@@ -163,12 +167,37 @@ When you select a project, the last conversation is automatically resumed. Tap "
 
 Tokens are redacted from Telegram output and logs. If the encrypted vault is unlocked, `/use_oauth_token` also mirrors the token into the vault, but `.env` storage is what lets launchd pass `CLAUDE_CODE_OAUTH_TOKEN` to Claude without relying on macOS Keychain.
 
+### Codex Auth
+
+| Command | Description |
+|---------|-------------|
+| `/codex_auth_status` | Runs `codex login status` and reports redacted status/version |
+| `/codex_login` | Starts `codex login --device-auth` and sends any login URL/device code printed by the CLI |
+| `/codex_setup_token` | Secure paste mode for an OpenAI API key; the message is deleted and passed to `codex login --with-api-key` without echoing it |
+| `/codex_setup_token <key>` | Same as above, but inline; the command message is deleted when possible |
+| `/cancel_codex_auth` | Cancels a pending Codex auth flow |
+
+Codex tokens/API keys are redacted from Telegram output and logs. Device login support depends on the installed Codex CLI; if it requires a real TTY, Open Claudia will say so and suggest `/codex_setup_token` or an SSH/terminal fallback.
+
+### Requirements Doctor
+
+`/doctor` (alias: `/requirements`) gives a mobile-friendly checklist after upgrades or whenever something feels broken:
+
+- Node.js version
+- Claude CLI version/auth
+- Cursor Agent version/status when installed/configured
+- Codex CLI version/auth when installed/configured
+- ffmpeg/Whisper/model paths when voice is configured
+- Workspace and config directory writability
+
+`/upgrade` also includes a post-upgrade doctor summary before restarting.
 
 ### System
 
 | Command | Description |
 |---------|-------------|
 | `/version` | Show current running version |
+| `/doctor` / `/requirements` | Check installed CLI requirements/auth and writable paths |
 | `/upgrade` | Upgrade to latest version and restart |
 | `/restart` | Restart the bot |
 | `/stop` | Cancel a running task |
@@ -229,6 +258,15 @@ open-claudia auth
 
 This shows authorized chats, pending requests, and lets you approve/deny or add new users with code verification.
 
+Authorized chats are separate from identity links. By default each Telegram chat uses `telegram:<chatId>` as its user id. To share one session/history across channels later, link the chat to a canonical id:
+
+```text
+/link sumeet@inet.africa
+/whoami
+```
+
+The owner can link another Telegram chat with `/link <chatId> <email-or-user-id>` and list explicit links with `/links`.
+
 ## How It Works
 
 ```
@@ -249,6 +287,7 @@ All stored in `~/.open-claudia/`:
 |------|---------|
 | `.env` | Telegram token, workspace path, binary paths (`CLAUDE_PATH`, `CURSOR_PATH`) |
 | `auth.json` | Authorized users and pending requests |
+| `identities.json` | Channel-to-canonical-user mappings such as `telegram:<chatId> -> user@example.com` |
 | `vault.enc` | Encrypted credential store |
 | `soul.md` | Assistant identity and personality (editable via `/soul`) |
 | `crons.json` | Scheduled tasks |

package/bot.js

@@ -204,6 +204,7 @@ const SOUL_FILE = config.SOUL_FILE || path.join(CONFIG_DIR, "soul.md");
 const CRONS_FILE = config.CRONS_FILE || path.join(CONFIG_DIR, "crons.json");
 const VAULT_FILE = config.VAULT_FILE || path.join(CONFIG_DIR, "vault.enc");
 const AUTH_FILE = config.AUTH_FILE || path.join(CONFIG_DIR, "auth.json");
+const IDENTITIES_FILE = config.IDENTITIES_FILE || path.join(CONFIG_DIR, "identities.json");
 const BOT_DIR = __dirname;
 
 // Detect PATH for subprocess
@@ -303,7 +304,13 @@ bot.setMyCommands([
   { command: "claude", description: "Switch to Claude Code backend" },
   { command: "codex", description: "Switch to OpenAI Codex backend" },
   { command: "backend", description: "Show/switch active backend" },
+  { command: "doctor", description: "Check CLI requirements" },
+  { command: "requirements", description: "Check CLI requirements" },
+  { command: "link", description: "Link this chat to a canonical user id" },
+  { command: "whoami", description: "Show your canonical user id" },
   { command: "auth_status", description: "Check Claude Code auth" },
+  { command: "codex_auth_status", description: "Check Codex auth" },
+  { command: "codex_login", description: "Start Codex device login" },
   { command: "login", description: "Start Claude Code login" },
   { command: "setup_token", description: "Create Claude OAuth token" },
   { command: "stop", description: "Cancel running task" },
@@ -331,19 +338,85 @@ const MAX_PROCESS_TIMEOUT = 360 * 60 * 1000;
 const STATE_FILE = path.join(CONFIG_DIR, "state.json");
 const SESSIONS_FILE = path.join(CONFIG_DIR, "sessions.json");
 
+function normalizeCanonicalUserId(value) {
+  return String(value || "").trim().toLowerCase();
+}
+
+function channelKey(transport, channelId) {
+  return `${String(transport || "").trim().toLowerCase()}:${String(channelId || "").trim()}`;
+}
+
+function defaultCanonicalForChannel(transport, channelId) {
+  return channelKey(transport, channelId);
+}
+
+function loadIdentities() {
+  try {
+    const raw = JSON.parse(fs.readFileSync(IDENTITIES_FILE, "utf-8"));
+    return {
+      channels: raw && typeof raw.channels === "object" ? raw.channels : {},
+      preferred: raw && typeof raw.preferred === "object" ? raw.preferred : {},
+    };
+  } catch (e) {
+    return { channels: {}, preferred: {} };
+  }
+}
+
+const identities = loadIdentities();
+
+function saveIdentities() {
+  try { fs.writeFileSync(IDENTITIES_FILE, JSON.stringify(identities, null, 2)); } catch (e) {}
+}
+
+function canonicalForChannel(transport, channelId) {
+  const key = channelKey(transport, channelId);
+  return normalizeCanonicalUserId(identities.channels[key]) || defaultCanonicalForChannel(transport, channelId);
+}
+
+function canonicalForTelegram(chatId) {
+  return canonicalForChannel("telegram", chatId);
+}
+
+function canonicalForStoredUserKey(key) {
+  const id = String(key);
+  if (id.includes(":") || id.includes("@")) return normalizeCanonicalUserId(id);
+  return canonicalForTelegram(id);
+}
+
+function currentCanonicalUserId() {
+  return canonicalForTelegram(currentChatId());
+}
+
 function loadStateFile() {
   try { return JSON.parse(fs.readFileSync(STATE_FILE, "utf-8")); } catch (e) { return {}; }
 }
 
+function mergeSavedState(existing, next) {
+  return {
+    ...existing,
+    ...next,
+    settings: { ...(existing.settings || {}), ...(next.settings || {}) },
+    sessionUsage: { ...(existing.sessionUsage || {}), ...(next.sessionUsage || {}) },
+  };
+}
+
 // Multi-user state. v1.16 and earlier stored a single user's state at the
-// top level of state.json; v1.17+ stores `{ users: { "<chatId>": {...} } }`.
-// On first load, an old-format file is migrated to belong to CHAT_ID
-// (the bot owner) — direct-install users see no behavior change.
+// top level of state.json; v1.17/v1.18 stored `{ users: { "<chatId>": {...} } }`.
+// v1.19+ keys state by canonical user id (`telegram:<chatId>` by default,
+// or an explicit mapping like `sumeet@inet.africa`) so future transports can
+// share the same session state.
 const savedState = (() => {
   const raw = loadStateFile();
-  if (raw && raw.users && typeof raw.users === "object") return raw;
-  // Legacy single-user shape: hoist it under the owner's chat id.
-  return { users: { [CHAT_ID]: raw || {} } };
+  const users = {};
+  if (raw && raw.users && typeof raw.users === "object") {
+    for (const [key, value] of Object.entries(raw.users)) {
+      const userId = canonicalForStoredUserKey(key);
+      users[userId] = mergeSavedState(users[userId] || {}, value || {});
+    }
+    return { users };
+  }
+  // Legacy single-user shape: hoist it under the owner's canonical id.
+  return { users: { [canonicalForTelegram(CHAT_ID)]: raw || {} } };
 })();
 
 let activeCrons = new Map();
@@ -361,12 +434,13 @@ function freshUsage() {
   return { turns: 0, inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0, costUsd: 0, lastInputTokens: 0 };
 }
 
-function createUserState(chatId) {
-  const saved = (savedState.users && savedState.users[chatId]) || {};
+function createUserState(userId) {
+  const saved = (savedState.users && savedState.users[userId]) || {};
   const settings = saved.settings || freshSettings();
   if (!settings.backend) settings.backend = "claude";
   return {
-    chatId: String(chatId),
+    userId: String(userId),
+    chatId: currentChatId(),
     currentSession: saved.currentSession || null,
     runningProcess: null,
     statusMessageId: null,
@@ -386,15 +460,19 @@ function createUserState(chatId) {
     pendingVaultAction: null,
     pendingClaudeAuthProcess: null,
     pendingClaudeAuthLabel: null,
+    pendingCodexAuthProcess: null,
+    pendingCodexAuthLabel: null,
     isCompacting: false,
     lastCompactedAt: saved.lastCompactedAt || 0,
   };
 }
 
-function getUserState(chatId) {
-  const id = String(chatId);
+function getUserState(userId) {
+  const id = normalizeCanonicalUserId(userId);
   if (!userStates.has(id)) userStates.set(id, createUserState(id));
-  return userStates.get(id);
+  const state = userStates.get(id);
+  state.chatId = currentChatId();
+  return state;
 }
 
 // AsyncLocalStorage carries the active chat id through the async call
@@ -408,7 +486,7 @@ function currentChatId() {
 }
 
 function currentState() {
-  return getUserState(currentChatId());
+  return getUserState(currentCanonicalUserId());
 }
 
 function resetSessionUsage(state = currentState()) {
@@ -420,7 +498,7 @@ function resetSettings(state = currentState()) {
 }
 
 function saveState() {
-  const data = { users: {} };
+  const data = { users: { ...(savedState.users || {}) } };
   for (const [id, s] of userStates) {
     data.users[id] = {
       currentSession: s.currentSession,
@@ -432,9 +510,64 @@ function saveState() {
       lastCompactedAt: s.lastCompactedAt || 0,
     };
   }
+  savedState.users = data.users;
   try { fs.writeFileSync(STATE_FILE, JSON.stringify(data)); } catch (e) {}
 }
 
+function migrateUserData(fromUserId, toUserId) {
+  const from = normalizeCanonicalUserId(fromUserId);
+  const to = normalizeCanonicalUserId(toUserId);
+  if (!from || !to || from === to) return;
+
+  if (savedState.users && savedState.users[from]) {
+    savedState.users[to] = mergeSavedState(savedState.users[to] || {}, savedState.users[from]);
+    delete savedState.users[from];
+  }
+
+  if (userStates.has(from)) {
+    const fromState = userStates.get(from);
+    if (userStates.has(to)) {
+      const toState = userStates.get(to);
+      Object.assign(toState, mergeSavedState(toState, fromState));
+      toState.userId = to;
+    } else {
+      fromState.userId = to;
+      userStates.set(to, fromState);
+    }
+    userStates.delete(from);
+  }
+
+  const sessions = loadSessions();
+  if (sessions[from]) {
+    sessions[to] = { ...(sessions[to] || {}) };
+    for (const [project, list] of Object.entries(sessions[from])) {
+      sessions[to][project] = [
+        ...(sessions[to][project] || []),
+        ...(Array.isArray(list) ? list : []),
+      ].slice(-20);
+    }
+    delete sessions[from];
+    saveSessions(sessions);
+  }
+
+  saveState();
+}
+
+function setIdentityMapping(transport, channelId, canonicalUserId) {
+  const key = channelKey(transport, channelId);
+  const userId = normalizeCanonicalUserId(canonicalUserId);
+  if (!userId) throw new Error("Canonical user id is required.");
+  const hadExplicitMapping = Object.prototype.hasOwnProperty.call(identities.channels, key);
+  const previousUserId = canonicalForChannel(transport, channelId);
+  const defaultUserId = defaultCanonicalForChannel(transport, channelId);
+  identities.channels[key] = userId;
+  identities.preferred[userId] = { transport: String(transport).toLowerCase(), channelId: String(channelId) };
+  saveIdentities();
+  const shouldMigrate = !hadExplicitMapping || previousUserId === defaultUserId;
+  if (shouldMigrate) migrateUserData(previousUserId, userId);
+  return { key, previousUserId, userId, migrated: shouldMigrate && previousUserId !== userId };
+}
+
 // ── Message deduplication ──────────────────────────────────────────
 // Telegram message_ids are unique per chat, not globally — namespace by
 // chat id so two users' messages can't collide.
@@ -452,9 +585,9 @@ function isDuplicate(msg) {
 }
 
 // ── Per-project session history ────────────────────────────────────
-// Sessions are stored per-chat so each user has their own conversation
-// history per project. Legacy single-user files are migrated under
-// CHAT_ID on first read.
+// Sessions are stored per canonical user so linked channels share the same
+// conversation history per project. Legacy files keyed by chat id are migrated
+// through the same identity resolver on first read.
 
 function loadSessions() {
   let raw;
@@ -462,17 +595,28 @@ function loadSessions() {
   if (!raw || typeof raw !== "object") return {};
   // Legacy detection: top-level keys map directly to arrays of session objects.
   const looksLegacy = Object.values(raw).some((v) => Array.isArray(v));
-  if (looksLegacy) return { [CHAT_ID]: raw };
-  return raw;
+  if (looksLegacy) return { [canonicalForTelegram(CHAT_ID)]: raw };
+  const migrated = {};
+  for (const [key, value] of Object.entries(raw)) {
+    const userId = canonicalForStoredUserKey(key);
+    migrated[userId] = { ...(migrated[userId] || {}) };
+    for (const [project, list] of Object.entries(value || {})) {
+      migrated[userId][project] = [
+        ...(migrated[userId][project] || []),
+        ...(Array.isArray(list) ? list : []),
+      ].slice(-20);
+    }
+  }
+  return migrated;
 }
 
 function saveSessions(sessions) {
   try { fs.writeFileSync(SESSIONS_FILE, JSON.stringify(sessions, null, 2)); } catch (e) {}
 }
 
-function recordSession(chatId, projectName, sessionId, title) {
+function recordSession(userId, projectName, sessionId, title) {
   const all = loadSessions();
-  const id = String(chatId);
+  const id = normalizeCanonicalUserId(userId);
   if (!all[id]) all[id] = {};
   if (!all[id][projectName]) all[id][projectName] = [];
   const arr = all[id][projectName];
@@ -492,13 +636,13 @@ function recordSession(chatId, projectName, sessionId, title) {
   saveSessions(all);
 }
 
-function getProjectSessions(chatId, projectName) {
+function getProjectSessions(userId, projectName) {
   const all = loadSessions();
-  return ((all[String(chatId)] || {})[projectName] || []).slice().reverse();
+  return ((all[normalizeCanonicalUserId(userId)] || {})[projectName] || []).slice().reverse();
 }
 
-function getLastProjectSession(chatId, projectName) {
-  const sessions = getProjectSessions(chatId, projectName);
+function getLastProjectSession(userId, projectName) {
+  const sessions = getProjectSessions(userId, projectName);
   return sessions.length > 0 ? sessions[0] : null;
 }
 
@@ -875,6 +1019,226 @@ async function deleteMessage(msgId) {
 }
 
 
+// ── Requirements / Doctor Helpers ──────────────────────────────────
+
+function shellQuote(value) {
+  return `"${String(value).replace(/"/g, '\\"')}"`;
+}
+
+function runCommandForDoctor(command, args = [], opts = {}) {
+  try {
+    const out = execSync([command, ...args].map(shellQuote).join(" "), {
+      cwd: opts.cwd || process.env.HOME || require("os").homedir(),
+      env: opts.env || botSubprocessEnv(),
+      encoding: "utf-8",
+      timeout: opts.timeout || 10000,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    return { ok: true, output: out.trim(), code: 0 };
+  } catch (e) {
+    return { ok: false, output: `${e.stdout || ""}\n${e.stderr || ""}\n${e.message || ""}`.trim(), code: e.status ?? 1 };
+  }
+}
+
+function binaryCheck(binPath, name) {
+  if (!binPath) return { ok: false, label: name, detail: "not configured/found" };
+  try {
+    if (fs.existsSync(binPath)) fs.accessSync(binPath, fs.constants.X_OK);
+    else execSync(process.platform === "win32" ? `where ${shellQuote(binPath)}` : `which ${shellQuote(binPath)}`, { stdio: "ignore", env: botSubprocessEnv() });
+    return { ok: true, label: name, detail: binPath };
+  } catch (e) {
+    return { ok: false, label: name, detail: `not executable: ${binPath}` };
+  }
+}
+
+function checkWritableDir(dirPath, label) {
+  if (!dirPath) return { ok: false, label, detail: "not configured" };
+  try {
+    if (!fs.existsSync(dirPath)) fs.mkdirSync(dirPath, { recursive: true });
+    const test = path.join(dirPath, `.open-claudia-write-test-${Date.now()}`);
+    fs.writeFileSync(test, "ok");
+    fs.unlinkSync(test);
+    return { ok: true, label, detail: dirPath };
+  } catch (e) {
+    return { ok: false, label, detail: redactSensitive(e.message) };
+  }
+}
+
+function summarizeAuthOutput(output, ok) {
+  const clean = redactSensitive(stripTerminalControls(output || "")).replace(/\s+/g, " ").trim();
+  if (!clean) return ok ? "ok" : "no output";
+  return clean.length > 160 ? clean.slice(0, 157) + "..." : clean;
+}
+
+function isCodexAuthErrorText(text) {
+  return /not (?:logged in|authenticated)|unauthenticated|login required|please (?:log|sign) in|401 unauthorized|invalid api key|no credentials/i.test(String(text || ""));
+}
+
+function runDoctorChecks() {
+  const checks = [];
+  const nodeMajor = parseInt(process.version.slice(1).split(".")[0], 10);
+  checks.push({ ok: nodeMajor >= 18, label: "Node.js", detail: process.version, action: nodeMajor >= 18 ? "" : "Install Node.js 18+." });
+
+  const claudeBin = binaryCheck(CLAUDE_PATH, "Claude CLI");
+  if (claudeBin.ok) {
+    const ver = runCommandForDoctor(CLAUDE_PATH, ["--version"]);
+    const auth = runCommandForDoctor(CLAUDE_PATH, ["auth", "status"], { env: claudeSubprocessEnv(), timeout: 12000 });
+    checks.push({ ok: ver.ok, label: "Claude version", detail: summarizeAuthOutput(ver.output, ver.ok), action: ver.ok ? "" : "Check CLAUDE_PATH." });
+    checks.push({ ok: auth.ok && !isClaudeAuthErrorText(auth.output), label: "Claude auth", detail: summarizeAuthOutput(auth.output, auth.ok), action: auth.ok && !isClaudeAuthErrorText(auth.output) ? "" : "Run /auth_status then /setup_token or /login." });
+  } else checks.push({ ...claudeBin, action: "Install @anthropic-ai/claude-code or fix CLAUDE_PATH." });
+
+  if (CURSOR_PATH || resolvedCursorPath) {
+    const cursorPath = resolvedCursorPath || CURSOR_PATH;
+    const cursorBin = binaryCheck(cursorPath, "Cursor Agent");
+    if (cursorBin.ok) {
+      const ver = runCommandForDoctor(cursorPath, ["--version"]);
+      const status = runCommandForDoctor(cursorPath, ["status"], { timeout: 12000 });
+      checks.push({ ok: ver.ok, label: "Cursor version", detail: summarizeAuthOutput(ver.output, ver.ok), action: ver.ok ? "" : "Check CURSOR_PATH." });
+      checks.push({ ok: status.ok, label: "Cursor auth/status", detail: summarizeAuthOutput(status.output, status.ok), action: status.ok ? "" : "Run `agent login` on this host." });
+    } else checks.push({ ...cursorBin, action: "Install Cursor Agent or fix CURSOR_PATH." });
+  } else checks.push({ ok: true, warn: true, label: "Cursor Agent", detail: "not configured/found (optional)", action: "Install only if you want /cursor." });
+
+  if (CODEX_PATH || resolvedCodexPath) {
+    const codexPath = resolvedCodexPath || CODEX_PATH;
+    const codexBin = binaryCheck(codexPath, "Codex CLI");
+    if (codexBin.ok) {
+      const ver = runCommandForDoctor(codexPath, ["--version"]);
+      const status = runCommandForDoctor(codexPath, ["login", "status"], { timeout: 12000 });
+      checks.push({ ok: ver.ok, label: "Codex version", detail: summarizeAuthOutput(ver.output, ver.ok), action: ver.ok ? "" : "Check CODEX_PATH." });
+      checks.push({ ok: status.ok && !isCodexAuthErrorText(status.output), label: "Codex auth", detail: summarizeAuthOutput(status.output, status.ok), action: status.ok && !isCodexAuthErrorText(status.output) ? "" : "Run /codex_login or /codex_setup_token." });
+    } else checks.push({ ...codexBin, action: "Install @openai/codex or fix CODEX_PATH." });
+  } else checks.push({ ok: true, warn: true, label: "Codex CLI", detail: "not configured/found (optional)", action: "Install only if you want /codex." });
+
+  if (FFMPEG || WHISPER_CLI || WHISPER_MODEL) {
+    const ff = binaryCheck(FFMPEG || "ffmpeg", "ffmpeg");
+    const wh = binaryCheck(WHISPER_CLI, "Whisper CLI");
+    checks.push({ ...ff, action: ff.ok ? "" : "Install ffmpeg or set FFMPEG." });
+    checks.push({ ...wh, action: wh.ok ? "" : "Install whisper.cpp or set WHISPER_CLI." });
+    checks.push({ ok: !!WHISPER_MODEL && fs.existsSync(WHISPER_MODEL), label: "Whisper model", detail: WHISPER_MODEL || "not configured", action: WHISPER_MODEL ? "Check model path." : "Set WHISPER_MODEL for voice notes." });
+  } else checks.push({ ok: true, warn: true, label: "Voice stack", detail: "not configured (optional)", action: "Set FFMPEG/WHISPER_CLI/WHISPER_MODEL for voice notes." });
+
+  checks.push(checkWritableDir(WORKSPACE, "Workspace writable"));
+  checks.push(checkWritableDir(CONFIG_DIR, "Config dir writable"));
+  return checks;
+}
+
+function formatDoctorReport(checks) {
+  const hardProblems = checks.filter((c) => !c.ok && !c.warn);
+  const warnings = checks.filter((c) => c.warn || (!c.ok && c.warn));
+  const lines = [hardProblems.length ? "⚠️ Open Claudia doctor found issues" : "✅ Open Claudia doctor looks good", ""];
+  for (const c of checks) {
+    const icon = c.ok ? (c.warn ? "⚠️" : "✅") : "⚠️";
+    lines.push(`${icon} ${c.label}: ${c.detail || (c.ok ? "ok" : "issue")}`);
+  }
+  const actions = checks.filter((c) => (!c.ok || c.warn) && c.action).map((c) => `• ${c.label}: ${c.action}`);
+  if (actions.length) lines.push("", "Next actions:", ...actions.slice(0, 8));
+  if (warnings.length && !hardProblems.length) lines[0] = "✅ Core requirements pass (optional items noted)";
+  return lines.join("\n");
+}
+
+function looksLikeOpenAIKey(value) {
+  return /^sk-(?:proj-)?[A-Za-z0-9._-]{20,}$/.test(String(value || "").trim());
+}
+
+function clearPendingCodexAuth(state = currentState()) {
+  if (state.pendingCodexAuthProcess && state.pendingCodexAuthProcess.kill) {
+    try { state.pendingCodexAuthProcess.kill("SIGTERM"); } catch (e) {}
+  }
+  state.pendingCodexAuthProcess = null;
+  state.pendingCodexAuthLabel = null;
+}
+
+function runCodexLoginStatus() {
+  if (!resolvedCodexPath) return { ok: false, code: 1, output: "Codex CLI not found" };
+  const result = runCommandForDoctor(resolvedCodexPath, ["login", "status"], { timeout: 12000 });
+  return { ...result, ok: result.ok && !isCodexAuthErrorText(result.output) };
+}
+
+async function sendCodexAuthStatusSummary(prefix = "Codex auth status") {
+  const status = runCodexLoginStatus();
+  const version = resolvedCodexPath ? runCommandForDoctor(resolvedCodexPath, ["--version"]) : { ok: false, output: "not found" };
+  await send([
+    prefix,
+    "",
+    `CLI: ${resolvedCodexPath ? "found" : "not found"}`,
+    `Version: ${summarizeAuthOutput(version.output, version.ok)}`,
+    `Logged in: ${status.ok ? "yes" : "no/unknown"}`,
+    `Status: ${summarizeAuthOutput(status.output, status.ok)}`,
+    status.ok ? "" : "Next: /codex_login for device auth, or /codex_setup_token to paste an OpenAI API key securely.",
+  ].filter(Boolean).join("\n"));
+}
+
+async function saveCodexApiKeyWithCli(apiKey) {
+  return new Promise((resolve) => {
+    const proc = spawn(resolvedCodexPath, ["login", "--with-api-key"], {
+      cwd: process.env.HOME || require("os").homedir(),
+      env: botSubprocessEnv(),
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    let output = "";
+    proc.stdout.on("data", (d) => { output += d.toString(); });
+    proc.stderr.on("data", (d) => { output += d.toString(); });
+    proc.on("close", (code) => resolve({ ok: code === 0, code, output }));
+    proc.on("error", (err) => resolve({ ok: false, code: 1, output: err.message }));
+    proc.stdin.write(apiKey.trim() + "\n");
+    proc.stdin.end();
+  });
+}
+
+async function runCodexDeviceLogin() {
+  const state = currentState();
+  if (!resolvedCodexPath) return send("Codex CLI not found. Install: npm install -g @openai/codex");
+  if (state.pendingCodexAuthProcess) return send(`Another Codex auth flow is already running (${state.pendingCodexAuthLabel}). Send /cancel_codex_auth to cancel.`);
+  await send("Codex device login started. I’ll send the URL/code if the CLI prints one.");
+  const proc = spawn(resolvedCodexPath, ["login", "--device-auth"], {
+    cwd: process.env.HOME || require("os").homedir(),
+    env: botSubprocessEnv(),
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+  state.pendingCodexAuthProcess = proc;
+  state.pendingCodexAuthLabel = "Codex device login";
+  let output = "";
+  let sent = new Set();
+  let lastSnippetAt = 0;
+  const handleChunk = async (chunk) => {
+    output += chunk;
+    const cleanChunk = redactSensitive(stripTerminalControls(chunk));
+    for (const url of extractUrls(cleanChunk)) {
+      if (!sent.has(url)) {
+        sent.add(url);
+        await send(`Codex login URL:\n${redactSensitive(url)}\n\nOpen it and enter the device code if shown.`);
+      }
+    }
+    const codeMatch = cleanChunk.match(/(?:code|device code)[:\s]+([A-Z0-9-]{6,})/i);
+    if (codeMatch && !sent.has(codeMatch[1])) {
+      sent.add(codeMatch[1]);
+      await send(`Codex device code: ${codeMatch[1]}`);
+    }
+    const now = Date.now();
+    if (cleanChunk.trim() && /device|code|login|browser|open|auth|token|error|failed|api key/i.test(cleanChunk) && now - lastSnippetAt > 3000) {
+      lastSnippetAt = now;
+      await send(cleanChunk.trim().slice(-1200));
+    }
+  };
+  proc.stdout.on("data", (d) => handleChunk(d.toString()).catch((e) => console.error("Codex auth output error:", e.message)));
+  proc.stderr.on("data", (d) => handleChunk(d.toString()).catch((e) => console.error("Codex auth stderr error:", e.message)));
+  proc.on("close", async (code) => {
+    state.pendingCodexAuthProcess = null;
+    state.pendingCodexAuthLabel = null;
+    const clean = redactSensitive(stripTerminalControls(output)).trim();
+    if (/raw mode is not supported|not a tty|inappropriate ioctl/i.test(clean)) {
+      await send("Codex device login could not complete inside Telegram on this host. Use /codex_setup_token to paste an OpenAI API key securely, or run `codex login --device-auth` in an SSH/terminal session.");
+    } else if (clean) await send(`Codex login finished (exit ${code}).\n\n${clean.slice(-2000)}`);
+    else await send(`Codex login finished (exit ${code}).`);
+    await sendCodexAuthStatusSummary("Post-Codex-auth check:");
+  });
+  proc.on("error", async (err) => {
+    state.pendingCodexAuthProcess = null;
+    state.pendingCodexAuthLabel = null;
+    await send(`Codex login failed: ${redactSensitive(err.message)}`);
+  });
+}
+
 // ── Claude Auth Helpers ─────────────────────────────────────────────
 
 const CLAUDE_OAUTH_TOKEN_KEY = "CLAUDE_CODE_OAUTH_TOKEN";
@@ -883,9 +1247,12 @@ const CLAUDE_OAUTH_VAULT_KEY = "claude_oauth_token";
 function redactSensitive(value) {
   return String(value || "")
     .replace(/sk-ant-[A-Za-z0-9._-]+/g, "[REDACTED_TOKEN]")
+    .replace(/sk-proj-[A-Za-z0-9._-]+/g, "[REDACTED_OPENAI_KEY]")
+    .replace(/sk-[A-Za-z0-9._-]{20,}/g, "[REDACTED_OPENAI_KEY]")
     .replace(/(Bearer\s+)[A-Za-z0-9._=-]+/gi, "$1[REDACTED_TOKEN]")
     .replace(/(CLAUDE_CODE_OAUTH_TOKEN\s*=\s*)\S+/gi, "$1[REDACTED_TOKEN]")
-    .replace(/([?&](?:token|access_token|refresh_token)=)[^\s&]+/gi, "$1[REDACTED]");
+    .replace(/(OPENAI_API_KEY\s*=\s*)\S+/gi, "$1[REDACTED_OPENAI_KEY]")
+    .replace(/([?&](?:token|access_token|refresh_token|api_key)=)[^\s&]+/gi, "$1[REDACTED]");
 }
 
 
@@ -945,8 +1312,12 @@ function getClaudeOAuthToken() {
   return { value: null, source: null };
 }
 
+function botSubprocessEnv() {
+  return { ...process.env, PATH: FULL_PATH, HOME: process.env.HOME || require("os").homedir() };
+}
+
 function claudeSubprocessEnv() {
-  const env = { ...process.env, PATH: FULL_PATH, HOME: process.env.HOME };
+  const env = botSubprocessEnv();
   const token = getClaudeOAuthToken().value;
   if (token) env.CLAUDE_CODE_OAUTH_TOKEN = token;
   return env;
@@ -1330,7 +1701,7 @@ function compactSeedPrompt(summary) {
 
 async function runClaudeCapture(prompt, cwd, opts = {}) {
   const state = currentState();
-  const chatId = state.chatId;
+  const chatId = currentChatId();
   if (state.runningProcess) throw new Error("Another task is already running.");
   const authPreflight = preflightClaudeAuthMessage();
   if (authPreflight) throw new Error(authPreflight);
@@ -1441,7 +1812,7 @@ async function compactActiveSession(cwd, opts = {}) {
 
     if (newSessionId && state.currentSession) {
       const title = `Compacted ${new Date().toLocaleDateString()}`;
-      recordSession(state.chatId, state.currentSession.name, newSessionId, title);
+      recordSession(state.userId, state.currentSession.name, newSessionId, title);
     }
     return { compacted: true, oldSessionId, newSessionId, summary };
   } finally {
@@ -1456,7 +1827,7 @@ async function runClaude(prompt, cwd, replyToMsgId, opts = {}) {
   // propagation through child_process events isn't guaranteed across all
   // Node versions.
   const state = currentState();
-  const chatId = state.chatId;
+  const chatId = currentChatId();
   const { settings } = state;
 
   if (state.runningProcess) {
@@ -1694,7 +2065,7 @@ async function runClaude(prompt, cwd, replyToMsgId, opts = {}) {
       return;
     }
     if (settings.backend === "codex" && /not (?:logged in|authenticated)|please (?:log|sign) in|401 unauthorized|invalid api key/i.test(stderrBuffer)) {
-      await send("Codex authentication error. Run `codex login` on this machine, then retry.", { replyTo: replyToMsgId });
+      await send("Codex authentication error. Try /codex_auth_status, then /codex_login or /codex_setup_token.", { replyTo: replyToMsgId });
       return;
     }
 
@@ -1742,7 +2113,7 @@ async function runClaude(prompt, cwd, replyToMsgId, opts = {}) {
     // Record session with auto-title from first message
     if (state.lastSessionId && state.currentSession) {
       const title = state.isFirstMessage ? (prompt.length > 60 ? prompt.slice(0, 57) + "..." : prompt) : null;
-      recordSession(chatId, state.currentSession.name, state.lastSessionId, title);
+      recordSession(state.userId, state.currentSession.name, state.lastSessionId, title);
       state.isFirstMessage = false;
     }
     if (state.messageQueue.length > 0 && state.currentSession) {
@@ -1832,14 +2203,14 @@ function startSession(name, resumeSessionId) {
   // Resume a specific session or the last one for this project
   if (resumeSessionId) {
     state.lastSessionId = resumeSessionId;
-    const sessions = getProjectSessions(state.chatId, projectName);
+    const sessions = getProjectSessions(state.userId, projectName);
     const s = sessions.find((x) => x.id === resumeSessionId);
     const title = s ? s.title : "";
     state.isFirstMessage = false;
     saveState();
     send(`Session: ${projectName}\nResumed: ${title || resumeSessionId.slice(0, 8)}\n\nSend text, voice, or images.\n\n/sessions — switch conversation\n/session — switch project`);
   } else {
-    const last = getLastProjectSession(state.chatId, projectName);
+    const last = getLastProjectSession(state.userId, projectName);
     if (last) {
       state.lastSessionId = last.id;
       state.isFirstMessage = false;
@@ -1893,15 +2264,71 @@ bot.onText(/\/help/, wrapHandler((msg) => {
   send([
     "Session: /session /sessions /projects /continue /status /stop /end",
     "Settings: /model /effort /budget /plan /compact /worktree /mode",
+    "Identity: /whoami /link",
     "Automation: /cron /vault /soul",
     "Claude auth: /auth_status /login /setup_token /use_oauth_token /clear_oauth_token",
-    "System: /restart /upgrade",
+    "Codex auth: /codex_auth_status /codex_login /codex_setup_token",
+    "System: /doctor /requirements /restart /upgrade",
     "",
     "Send text, voice, photos, or files.",
     "Reply to any message for context.",
   ].join("\n"));
 }));
 
+bot.onText(/\/whoami$/, wrapHandler((msg) => {
+  if (!isAuthorized(msg)) return;
+  const chatId = String(msg.chat.id);
+  const key = channelKey("telegram", chatId);
+  const userId = canonicalForTelegram(chatId);
+  const preferred = identities.preferred[userId];
+  send([
+    `Channel: ${key}`,
+    `User: ${userId}`,
+    preferred ? `Preferred: ${preferred.transport}:${preferred.channelId}` : "Preferred: this channel",
+  ].join("\n"));
+}));
+
+bot.onText(/\/links$/, wrapHandler((msg) => {
+  if (!isOwner(msg)) return;
+  const rows = Object.entries(identities.channels)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([channel, userId]) => `${channel} -> ${userId}`);
+  send(rows.length ? rows.join("\n") : "No explicit identity links. Unlinked Telegram chats use telegram:<chatId>.");
+}));
+
+bot.onText(/\/link$/, wrapHandler((msg) => {
+  if (!isAuthorized(msg)) return;
+  send(isOwner(msg)
+    ? "Usage:\n/link <email-or-user-id>\n/link <telegram-chat-id> <email-or-user-id>\n/link telegram:<chat-id> <email-or-user-id>\n\nOwner can link any Telegram chat; other users can link only their current chat."
+    : "Usage:\n/link <email-or-user-id>\n\nThis links your Telegram chat to a canonical user id.");
+}));
+
+bot.onText(/\/link\s+(.+)$/, wrapHandler((msg, match) => {
+  if (!isAuthorized(msg)) return;
+  const parts = String(match[1] || "").trim().split(/\s+/).filter(Boolean);
+  if (parts.length === 0 || parts.length > 2) return send("Usage: /link <email-or-user-id>");
+
+  let targetChatId = String(msg.chat.id);
+  let userId = parts[0];
+  if (parts.length === 2) {
+    if (!isOwner(msg)) return send("Only the owner can link another chat.");
+    const channel = parts[0];
+    if (channel.startsWith("telegram:")) targetChatId = channel.slice("telegram:".length);
+    else targetChatId = channel;
+    userId = parts[1];
+  }
+
+  if (!/^-?\d+$/.test(targetChatId)) return send("Telegram chat id must be numeric.");
+  const normalizedUserId = normalizeCanonicalUserId(userId);
+  if (!normalizedUserId || /\s/.test(normalizedUserId)) return send("Canonical user id cannot be empty or contain spaces.");
+
+  const result = setIdentityMapping("telegram", targetChatId, normalizedUserId);
+  send([
+    `Linked ${result.key} -> ${result.userId}`,
+    result.migrated ? `Migrated state from ${result.previousUserId}.` : "Existing canonical state was left in place.",
+  ].join("\n"));
+}));
+
 bot.onText(/\/version$/, wrapHandler((msg) => {
   if (!isAuthorized(msg)) return;
   send(`Open Claudia v${CURRENT_VERSION}`);
@@ -1964,8 +2391,9 @@ bot.onText(/\/upgrade$/, wrapHandler(async (msg) => {
         whatsNew = section.trim();
       }
     } catch (e) { /* no changelog */ }
-    const msg = `Installed v${newPkg.version}.${whatsNew ? `\n\nWhat's new:\n${whatsNew}` : ""}\n\nGoing offline to restart...`;
-    await send(msg);
+    const doctorReport = formatDoctorReport(runDoctorChecks());
+    const msg = `Installed v${newPkg.version}.${whatsNew ? `\n\nWhat's new:\n${whatsNew}` : ""}\n\nPost-upgrade requirements check:\n${doctorReport}\n\nGoing offline to restart...`;
+    await send(msg.length > 3900 ? msg.slice(0, 3900) : msg);
   } catch (e) {
     const errOutput = (e.stdout || e.stderr || e.message || "").slice(-500);
     await send(`Upgrade failed:\n${errOutput}`);
@@ -1988,7 +2416,7 @@ bot.onText(/\/sessions$/, wrapHandler((msg) => {
   if (!isAuthorized(msg)) return;
   if (!requireSession(msg)) return;
   const state = currentState();
-  const sessions = getProjectSessions(state.chatId, state.currentSession.name);
+  const sessions = getProjectSessions(state.userId, state.currentSession.name);
   if (sessions.length === 0) return send("No past conversations for this project.");
   const rows = sessions.slice(0, 10).map((s) => {
     const date = new Date(s.lastUsed).toLocaleDateString();
@@ -2202,6 +2630,11 @@ bot.onText(/\/stop/, wrapHandler(async (msg) => {
   else await send("Nothing running.");
 }));
 
+bot.onText(/\/(?:doctor|requirements)$/, wrapHandler(async (msg) => {
+  if (!isAuthorized(msg)) return;
+  await send(formatDoctorReport(runDoctorChecks()));
+}));
+
 bot.onText(/\/status/, wrapHandler((msg) => {
   if (!isAuthorized(msg)) return;
   const state = currentState();
@@ -2348,6 +2781,42 @@ bot.onText(/\/clear_oauth_token$/, wrapHandler(async (msg) => {
   await send("Claude OAuth token cleared from .env/process" + (vault.isUnlocked() ? " and vault." : ". Unlock vault and run again if you also stored it there."));
 }));
 
+bot.onText(/\/(?:codex_auth_status|codex auth status)$/, wrapHandler(async (msg) => {
+  if (!isAuthorized(msg)) return;
+  await sendCodexAuthStatusSummary();
+}));
+
+bot.onText(/\/codex_login$/, wrapHandler(async (msg) => {
+  if (!isOwner(msg)) return send("Owner only — Codex auth is shared across users.");
+  await runCodexDeviceLogin();
+}));
+
+bot.onText(/\/cancel_codex_auth$/, wrapHandler(async (msg) => {
+  if (!isOwner(msg)) return send("Owner only — Codex auth is shared across users.");
+  const state = currentState();
+  if (!state.pendingCodexAuthProcess) return send("No Codex auth flow is pending.");
+  clearPendingCodexAuth(state);
+  await send("Codex auth flow cancelled. Normal messages will go to the assistant again.");
+}));
+
+bot.onText(/\/(?:codex_setup_token|codex_use_api_key)(?:\s+(.+))?$/, wrapHandler(async (msg, match) => {
+  if (!isOwner(msg)) return send("Owner only — Codex auth is shared across users.");
+  if (!resolvedCodexPath) return send("Codex CLI not found. Install: npm install -g @openai/codex");
+  const key = (match[1] || "").trim();
+  await deleteMessage(msg.message_id);
+  if (!key) {
+    const state = currentState();
+    state.pendingCodexAuthProcess = { kill: () => {} };
+    state.pendingCodexAuthLabel = "manual OpenAI API key save";
+    await send("Send the OpenAI API key in your next message. I’ll delete it and pass it to `codex login --with-api-key` without echoing it.");
+    return;
+  }
+  if (!looksLikeOpenAIKey(key)) return send("That does not look like an OpenAI API key. Not saved.");
+  const result = await saveCodexApiKeyWithCli(key);
+  await send(result.ok ? "Codex API key stored by the Codex CLI. I did not print it." : `Codex CLI could not store the API key: ${redactSensitive(result.output).slice(-800)}`);
+  await sendCodexAuthStatusSummary("Current Codex auth status:");
+}));
+
 // ── /vault with password protection ─────────────────────────────────
 // Vault is a single shared store. Lock state is global; the
 // password-unlock flow is per-user (pendingVaultUnlock lives on the
@@ -2560,7 +3029,7 @@ bot.on("voice", wrapHandler(async (msg) => {
     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(state.chatId, "typing");
+    bot.sendChatAction(currentChatId(), "typing");
     const oggPath = await downloadFile(msg.voice.file_id, ".ogg");
     const transcript = transcribeAudio(oggPath);
     try { fs.unlinkSync(oggPath); } catch (e) {}
@@ -2577,7 +3046,7 @@ bot.on("audio", wrapHandler(async (msg) => {
   if (!requireSession(msg)) return;
   const state = currentState();
   try {
-    bot.sendChatAction(state.chatId, "typing");
+    bot.sendChatAction(currentChatId(), "typing");
     const p = await downloadFile(msg.audio.file_id, path.extname(msg.audio.file_name || ".ogg"));
     const t = transcribeAudio(p);
     try { fs.unlinkSync(p); } catch (e) {}
@@ -2641,6 +3110,27 @@ bot.on("message", wrapHandler(async (msg) => {
   if (isDuplicate(msg)) return;
   const state = currentState();
 
+  // Handle pending manual Codex API key paste mode.
+  if (state.pendingCodexAuthProcess && state.pendingCodexAuthLabel === "manual OpenAI API key save") {
+    const text = msg.text.trim();
+    await deleteMessage(msg.message_id);
+    if (!looksLikeOpenAIKey(text)) {
+      clearPendingCodexAuth(state);
+      await send("That did not look like an OpenAI API key. Not saved.");
+      return;
+    }
+    clearPendingCodexAuth(state);
+    const result = await saveCodexApiKeyWithCli(text);
+    await send(result.ok ? "Codex API key stored by the Codex CLI. I did not print it." : `Codex CLI could not store the API key: ${redactSensitive(result.output).slice(-800)}`);
+    await sendCodexAuthStatusSummary("Current Codex auth status:");
+    return;
+  }
+
+  if (state.pendingCodexAuthProcess) {
+    await send("Codex login is still running. Complete the device flow in your browser, or send /cancel_codex_auth.");
+    return;
+  }
+
   // Handle pending manual OAuth token paste mode. Login codes must be sent explicitly
   // with /auth_code so normal chat can never be deleted/consumed accidentally.
   if (state.pendingClaudeAuthProcess && state.pendingClaudeAuthLabel === "manual OAuth token save") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inetafrica/open-claudia",
-  "version": "1.18.0",
+  "version": "1.19.0",
   "description": "Your always-on AI coding assistant — Claude Code, Cursor Agent, and OpenAI Codex via Telegram",
   "main": "bot.js",
   "bin": {