levix-bot 3.3.0-rc.2 → 4.0.0

package/src/config/vault.cjs

@@ -0,0 +1,107 @@
+// Data-at-rest encryption for high-value secrets.
+//
+// The WhatsApp session (baileys_auth) and operator API keys must not sit in
+// levix.db as plaintext. A 32-byte AES-256-GCM key is generated on first use
+// and stored as `levix.key` in the data directory (mode 0600), never in the
+// database — a leaked .db backup is not enough to recover the session or keys.
+//
+// On Android that directory is already the app-private files dir
+// (`/data/data/net.leviro.levix/files/data`). On a desktop install it is the
+// same folder as the database. Root on the device can still read both files;
+// this stops a copied database, a partial backup, or a casual file dump.
+//
+// Format: enc:v1:<iv_hex>.<tag_hex>.<ciphertext_hex>
+// Unsealed legacy values pass through `open()` so upgrades re-encrypt on write.
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+
+const logger = require("../utils/logger.cjs");
+
+const PREFIX = "enc:v1:";
+const KEY_BYTES = 32;
+const IV_BYTES = 12;
+const KEY_FILE = "levix.key";
+
+let cachedKey = null;
+
+function keyPath() {
+  const { dataPath, ensureDataDir } = require("./paths.cjs");
+  ensureDataDir();
+  return dataPath(KEY_FILE);
+}
+
+function loadMasterKey() {
+  if (cachedKey) return cachedKey;
+  const file = keyPath();
+  if (fs.existsSync(file)) {
+    const raw = fs.readFileSync(file);
+    if (raw.length === KEY_BYTES) {
+      cachedKey = raw;
+      return cachedKey;
+    }
+    const hex = raw.toString("utf8").trim();
+    if (/^[0-9a-f]{64}$/i.test(hex)) {
+      cachedKey = Buffer.from(hex, "hex");
+      return cachedKey;
+    }
+    throw new Error("levix.key is not a valid 32-byte encryption key");
+  }
+
+  const key = crypto.randomBytes(KEY_BYTES);
+  fs.writeFileSync(file, key, { mode: 0o600 });
+  try {
+    fs.chmodSync(file, 0o600);
+  } catch {
+    // Windows has no POSIX modes; the data directory still holds the file.
+  }
+  logger.info("[vault] Generated a new data-at-rest encryption key");
+  cachedKey = key;
+  return cachedKey;
+}
+
+function isSealed(value) {
+  return typeof value === "string" && value.startsWith(PREFIX);
+}
+
+function seal(plaintext) {
+  const text = plaintext == null ? "" : String(plaintext);
+  const key = loadMasterKey();
+  const iv = crypto.randomBytes(IV_BYTES);
+  const cipher = crypto.createCipheriv("aes-256-gcm", key, iv);
+  const encrypted = Buffer.concat([cipher.update(text, "utf8"), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return `${PREFIX}${iv.toString("hex")}.${tag.toString("hex")}.${encrypted.toString("hex")}`;
+}
+
+function open(value) {
+  if (value == null) return value;
+  if (!isSealed(value)) return value;
+  const body = value.slice(PREFIX.length);
+  const parts = body.split(".");
+  if (parts.length !== 3) throw new Error("Malformed sealed secret");
+  const [ivHex, tagHex, dataHex] = parts;
+  const key = loadMasterKey();
+  const decipher = crypto.createDecipheriv("aes-256-gcm", key, Buffer.from(ivHex, "hex"));
+  decipher.setAuthTag(Buffer.from(tagHex, "hex"));
+  return Buffer.concat([
+    decipher.update(Buffer.from(dataHex, "hex")),
+    decipher.final(),
+  ]).toString("utf8");
+}
+
+/** Reset the in-process key cache. Tests that switch data dirs need this. */
+function resetVaultCache() {
+  cachedKey = null;
+}
+
+module.exports = {
+  PREFIX,
+  KEY_FILE,
+  isSealed,
+  seal,
+  open,
+  loadMasterKey,
+  keyPath,
+  resetVaultCache,
+};

package/src/core/connection.js

@@ -11,13 +11,14 @@
 
 import { DisconnectReason } from "@whiskeysockets/baileys";
 import { createRequire } from "module";
-import { groupMetadataCache } from "./socket.js";
+import { bootstrapAdmins, bootstrapOwners } from "../utils/permissions.esm.js";
 import {
-  saveUserMetadata,
-  getAllOwners,
   getAllBotAdmins,
+  getAllOwners,
+  saveUserMetadata,
+  upsertGroupDirectory,
 } from "../utils/storage.esm.js";
-import { bootstrapOwners, bootstrapAdmins } from "../utils/permissions.esm.js";
+import { groupMetadataCache } from "./socket.js";
 
 const require = createRequire(import.meta.url);
 const logger = require("../utils/logger.cjs");
@@ -123,9 +124,7 @@ export async function handleConnectionOpen(sock, initializeScheduledJobs) {
   const botPn = sock?.user?.id
     ? `${sock.user.id.split(":")[0].split("@")[0]}@s.whatsapp.net`
     : null;
-  const botLid = sock?.user?.lid
-    ? `${sock.user.lid.split(":")[0].split("@")[0]}@lid`
-    : null;
+  const botLid = sock?.user?.lid ? `${sock.user.lid.split(":")[0].split("@")[0]}@lid` : null;
 
   // Both rosters are seeded from the database so a permission check never has
   // to hit it on the hot path.
@@ -144,7 +143,7 @@ export async function handleConnectionOpen(sock, initializeScheduledJobs) {
   await primePermissions();
   logger.info(
     `[Permissions] Owner roster: ${ownersRoster.length} entries; ` +
-      `admin roster: ${adminsRoster.length} entries`
+      `admin roster: ${adminsRoster.length} entries`,
   );
 
   // Called on every open, including a reconnect: scheduleNewJob() stops the
@@ -163,9 +162,7 @@ async function saveBotOwnerMetadata(sock) {
 
     const phoneNumber = sock?.user?.id?.split(":")[0]?.split("@")[0];
     const userJid = phoneNumber ? `${phoneNumber}@s.whatsapp.net` : null;
-    const userLid = sock?.user?.lid
-      ? `${sock.user.lid.split(":")[0].split("@")[0]}@lid`
-      : null;
+    const userLid = sock?.user?.lid ? `${sock.user.lid.split(":")[0].split("@")[0]}@lid` : null;
     const displayName = sock?.user?.name || sock?.user?.verifiedName || null;
 
     if (userJid) {
@@ -177,7 +174,7 @@ async function saveBotOwnerMetadata(sock) {
         displayName,
       });
       logger.info(
-        `[User Metadata] Saved bot owner: ${phoneNumber} (JID: ${userJid}, LID: ${userLid})`
+        `[User Metadata] Saved bot owner: ${phoneNumber} (JID: ${userJid}, LID: ${userLid})`,
       );
     }
   } catch (err) {
@@ -195,6 +192,10 @@ async function cacheAllGroups(sock) {
 
     for (const jid in groups) {
       groupMetadataCache.set(jid, groups[jid]);
+      upsertGroupDirectory(jid, {
+        subject: groups[jid]?.subject || null,
+        participantCount: groups[jid]?.participants?.length ?? null,
+      });
       cachedCount++;
     }
 

package/src/core/events.js

@@ -1,11 +1,14 @@
-import { createRequire } from 'module';
-import { handleIncomingMessage } from '../handlers/message.handler.js';
-import { handleGroupParticipantsUpdate, handleGroupJoinRequests } from '../handlers/group.handler.js';
-import { groupMetadataCache } from './socket.js';
-import { storeLidPnMappings } from '../utils/storage.esm.js';
+import { createRequire } from "module";
+import {
+  handleGroupJoinRequests,
+  handleGroupParticipantsUpdate,
+} from "../handlers/group.handler.js";
+import { handleIncomingMessage } from "../handlers/message.handler.js";
+import { storeLidPnMappings, upsertGroupDirectory } from "../utils/storage.esm.js";
+import { groupMetadataCache } from "./socket.js";
 
 const require = createRequire(import.meta.url);
-const logger = require('../utils/logger.cjs');
+const logger = require("../utils/logger.cjs");
 
 /**
  * Wire one socket up.
@@ -22,7 +25,7 @@ const logger = require('../utils/logger.cjs');
  */
 export function setupEventListeners(
   sock,
-  { saveCreds, onConnectionUpdate, onHandshakeRejected } = {}
+  { saveCreds, onConnectionUpdate, onHandshakeRejected } = {},
 ) {
   // Every listener below goes through this. A bare `async` listener hands its
   // promise to Baileys' emitter, which drops it — so one rejection anywhere in
@@ -36,8 +39,8 @@ export function setupEventListeners(
   };
 
   sock.ev.on(
-    'connection.update',
-    contained('connection.update', (update) => onConnectionUpdate?.(update))
+    "connection.update",
+    contained("connection.update", (update) => onConnectionUpdate?.(update)),
   );
 
   // A handshake the server answered with an HTTP status instead of an upgrade.
@@ -50,17 +53,17 @@ export function setupEventListeners(
   // therefore produced no error, no close and no connection.update at all: the
   // session simply sat in `starting` until somebody noticed.
   sock.ws?.on?.(
-    'unexpected-response',
-    contained('unexpected-response', (_request, response) => {
+    "unexpected-response",
+    contained("unexpected-response", (_request, response) => {
       onHandshakeRejected?.(response);
-    })
+    }),
   );
 
   // Save credentials
-  if (saveCreds) sock.ev.on('creds.update', saveCreds);
+  if (saveCreds) sock.ev.on("creds.update", saveCreds);
 
   // V7: LID mapping updates
-  sock.ev.on('lid-mapping.update', (updates) => {
+  sock.ev.on("lid-mapping.update", (updates) => {
     logger.info(`[LID] Received ${Object.keys(updates).length} LID mapping updates`);
     const mappings = [];
     for (const [lid, pn] of Object.entries(updates)) {
@@ -74,30 +77,45 @@ export function setupEventListeners(
   });
 
   // Group metadata updates
-  sock.ev.on('groups.upsert', (updates) => {
+  sock.ev.on("groups.upsert", (updates) => {
     for (const group of updates) {
       logger.info(`[Cache] Caching metadata for group: ${group.id}`);
       groupMetadataCache.set(group.id, group);
+      upsertGroupDirectory(group.id, {
+        subject: group.subject || null,
+        participantCount: group.participants?.length ?? null,
+      });
+    }
+  });
+
+  sock.ev.on("groups.update", (updates) => {
+    for (const group of updates || []) {
+      if (!group?.id) continue;
+      const current = groupMetadataCache.get(group.id) || {};
+      const next = { ...current, ...group };
+      groupMetadataCache.set(group.id, next);
+      upsertGroupDirectory(group.id, {
+        subject: next.subject || null,
+        participantCount: next.participants?.length ?? null,
+      });
     }
   });
 
   // Incoming messages
   sock.ev.on(
-    'messages.upsert',
-    contained('messages.upsert', (m) => handleIncomingMessage(sock, m))
+    "messages.upsert",
+    contained("messages.upsert", (m) => handleIncomingMessage(sock, m)),
   );
 
   // Group participant updates
   sock.ev.on(
-    'group-participants.update',
-    contained('group-participants.update', (update) =>
-      handleGroupParticipantsUpdate(sock, update)
-    )
+    "group-participants.update",
+    contained("group-participants.update", (update) => handleGroupParticipantsUpdate(sock, update)),
   );
 
   // Group join requests
   sock.ev.on(
-    'group-requests.update',
-    contained('group-requests.update', (events) => handleGroupJoinRequests(sock, events))
+    "group-requests.update",
+    contained("group-requests.update", (events) => handleGroupJoinRequests(sock, events)),
   );
 }

package/src/core/proxy.js

@@ -37,12 +37,12 @@
 // string, its result never reaches a log or an HTTP response, and everything
 // human-facing goes through `redactProxy()`.
 
-import { createRequire } from "module";
+import tls from "node:tls";
 import { HttpsProxyAgent } from "https-proxy-agent";
+import { createRequire } from "module";
+import { SocksClient } from "socks";
 import { SocksProxyAgent } from "socks-proxy-agent";
 import { Agent as UndiciAgent, ProxyAgent as UndiciProxyAgent } from "undici";
-import { SocksClient } from "socks";
-import tls from "node:tls";
 
 const require = createRequire(import.meta.url);
 const settings = require("../config/settings.cjs");
@@ -74,7 +74,9 @@ export function readProxyConfig() {
  */
 export function normalizeProxyConfig(raw = {}) {
   const enabled = raw.enabled === true || raw.enabled === "true" || raw.enabled === 1;
-  const protocol = String(raw.protocol ?? "http").trim().toLowerCase();
+  const protocol = String(raw.protocol ?? "http")
+    .trim()
+    .toLowerCase();
   const host = String(raw.host ?? "").trim();
   const port = Number(raw.port ?? 0);
   // Usernames and passwords are taken exactly as given except for surrounding
@@ -179,9 +181,7 @@ function socksDispatcher(config) {
     host: config.host,
     port: config.port,
     type: 5,
-    ...(config.username
-      ? { userId: config.username, password: config.password }
-      : {}),
+    ...(config.username ? { userId: config.username, password: config.password } : {}),
   };
 
   return new UndiciAgent({

package/src/core/session.js

@@ -46,14 +46,21 @@
 // Regenerating one forever is how the old code burned a socket a minute on
 // installs nobody was pairing.
 
-import { createRequire } from "module";
 import { DisconnectReason } from "@whiskeysockets/baileys";
-
-import { createWhatsAppSocket } from "./socket.js";
-import { setupEventListeners } from "./events.js";
-import { handleConnectionOpen, classifyDisconnect } from "./connection.js";
+import { createRequire } from "module";
 import { RETRY_SCHEDULE_MS } from "../config/constants.js";
-import { clearAuthState, deleteQrCode, saveQrCode } from "../utils/storage.esm.js";
+import {
+  clearAuthState,
+  clearWhatsAppDirectory,
+  deleteAllChatHistories,
+  deleteQrCode,
+  isPairedSession,
+  pauseAllSchedules,
+  saveQrCode,
+} from "../utils/storage.esm.js";
+import { bootstrapAdmins, bootstrapOwners } from "../utils/permissions.esm.js";
+import { classifyDisconnect, handleConnectionOpen } from "./connection.js";
+import { setupEventListeners } from "./events.js";
 import {
   createProxyAgents,
   describeProxyFailure,
@@ -61,10 +68,33 @@ import {
   readProxyConfig,
   redactProxy,
 } from "./proxy.js";
+import { createWhatsAppSocket, groupMetadataCache } from "./socket.js";
 
 const require = createRequire(import.meta.url);
 const logger = require("../utils/logger.cjs");
 
+function clearAccountScopedState() {
+  clearWhatsAppDirectory();
+  deleteAllChatHistories();
+  pauseAllSchedules();
+  bootstrapOwners([]);
+  bootstrapAdmins([]);
+
+  try {
+    require("../utils/memory.cjs").clearAllMemoryFiles();
+  } catch (error) {
+    logger.warn({ err: error }, "[Session] failed to clear AI memory after unlink");
+  }
+  try {
+    require("../commands/gemini.cjs").clearAllContextBuffers();
+  } catch (error) {
+    logger.warn({ err: error }, "[Session] failed to clear AI context buffers after unlink");
+  }
+  try {
+    groupMetadataCache.flushAll();
+  } catch {}
+}
+
 // Baileys' `end()` awaits `ws.close()`, which waits for the socket's own
 // 'close' event with no timeout of its own. A half-dead TCP connection can
 // therefore hang it forever — and this is on the SIGTERM path, so "forever"
@@ -89,14 +119,14 @@ export function normalizePairingPhone(input) {
   const digits = value.replace(/\D/g, "");
   if (digits.startsWith("0")) {
     const error = new Error(
-      "Drop the leading 0 and include the country code (e.g. 2010… not 010…)."
+      "Drop the leading 0 and include the country code (e.g. 2010… not 010…).",
     );
     error.code = "PAIRING_PHONE";
     throw error;
   }
   if (digits.length < 8 || digits.length > 15) {
     const error = new Error(
-      "Enter the WhatsApp number with country code, digits only (e.g. 2010…)."
+      "Enter the WhatsApp number with country code, digits only (e.g. 2010…).",
     );
     error.code = "PAIRING_PHONE";
     throw error;
@@ -221,12 +251,16 @@ export class WhatsAppSession {
     retryDelaysMs = RETRY_SCHEDULE_MS,
     log = logger,
     pairingCodeDelayMs = 1500,
+    isLinked = isPairedSession,
+    clearDirectory = clearAccountScopedState,
   } = {}) {
     this.createSocket = createSocket;
     this.attachListeners = attachListeners;
     this.onOpen = onOpen;
     this.initializeScheduledJobs = initializeScheduledJobs;
     this.stopScheduledJobs = stopScheduledJobs;
+    this.isLinked = isLinked;
+    this.clearDirectory = clearDirectory;
     this.loadProxy = loadProxy;
     this.buildProxyAgents = buildProxyAgents;
     this.emitEvent = emit;
@@ -271,9 +305,7 @@ export class WhatsAppSession {
   /** Everything the dashboard needs to render the Connection screen. */
   getState() {
     const terminal =
-      this.#state === S.LOGGED_OUT ||
-      this.#state === S.RETRY_EXHAUSTED ||
-      this.#state === S.ERROR;
+      this.#state === S.LOGGED_OUT || this.#state === S.RETRY_EXHAUSTED || this.#state === S.ERROR;
 
     return {
       state: this.#state,
@@ -288,6 +320,8 @@ export class WhatsAppSession {
       // leaves dead credentials behind, and unlinking is the only way out of
       // it. The one state with nothing to unlink is the one that just did.
       canUnlink: this.#state !== S.LOGGED_OUT && !this.#shuttingDown,
+      // Finished WhatsApp pairing — resume/connect, do not offer QR/pair.
+      linked: this.#state !== S.LOGGED_OUT && this.isLinked(),
       // Redacted — never the password. Null when the socket is direct.
       proxy: this.#proxyLabel,
       // True when the saved proxy settings differ from what the live socket was
@@ -300,8 +334,7 @@ export class WhatsAppSession {
       hasQr: !!this.#qr,
       hasPairingCode: !!this.#pairingCode,
       pairingMethod: this.#pairingIntent?.method || "qr",
-      pairingPhone:
-        this.#pairingIntent?.method === "pairing" ? this.#pairingIntent.phone : null,
+      pairingPhone: this.#pairingIntent?.method === "pairing" ? this.#pairingIntent.phone : null,
       reason: this.#reason,
       detail: this.#detail,
       lastDisconnect: this.#lastDisconnect,
@@ -333,8 +366,7 @@ export class WhatsAppSession {
 
     if (!isOnline) {
       this.log.warn("[Session] Device is offline — pausing WhatsApp connection and retries");
-      this.#wasActiveBeforeOffline =
-        BUSY_STATES.has(this.#state) || this.#state === S.PAUSED;
+      this.#wasActiveBeforeOffline = BUSY_STATES.has(this.#state) || this.#state === S.PAUSED;
       this.#cancelRetry();
 
       if (this.#socket) {
@@ -378,7 +410,12 @@ export class WhatsAppSession {
     }
     if (BUSY_STATES.has(this.#state) && this.#state !== S.PAUSED) return this.getState();
 
-    this.#pairingIntent = parseStartOptions({ method, phone });
+    // A known pairing reuses the stored session. Do not request a pairing code.
+    if (this.isLinked()) {
+      this.#pairingIntent = { method: "qr", phone: null };
+    } else {
+      this.#pairingIntent = parseStartOptions({ method, phone });
+    }
 
     // A manual start clears whatever the last failure left behind.
     this.#cancelRetry();
@@ -467,6 +504,13 @@ export class WhatsAppSession {
     this.#clearAll = null;
     this.#pairing = false;
     this.#clearQr();
+    this.#stopJobs();
+    try {
+      this.clearDirectory?.();
+    } catch (error) {
+      this.log.warn({ err: error }, "[Session] failed to clear WhatsApp directory after unlink");
+    }
+
     this.#transition(S.LOGGED_OUT, {
       reason: "unlinked",
       detail: "The WhatsApp account was unlinked. Start a session to pair a new one.",
@@ -534,10 +578,7 @@ export class WhatsAppSession {
       proxyConfig = this.loadProxy();
       proxy = this.buildProxyAgents(proxyConfig);
     } catch (error) {
-      this.log.error(
-        { err: error?.message },
-        "[Session] the proxy configuration is not usable"
-      );
+      this.log.error({ err: error?.message }, "[Session] the proxy configuration is not usable");
       this.#proxyFingerprint = null;
       this.#proxyLabel = null;
       this.#transition(S.ERROR, {
@@ -557,7 +598,7 @@ export class WhatsAppSession {
     try {
       created = await this.createSocket({
         proxy,
-        pairingCode: this.#pairingIntent.method === "pairing",
+        pairingCode: !this.isLinked() && this.#pairingIntent.method === "pairing",
       });
     } catch (error) {
       this.log.error({ err: error }, "[Session] failed to create the WhatsApp socket");
@@ -594,12 +635,10 @@ export class WhatsAppSession {
     this.attachListeners(sock, {
       saveCreds,
       onConnectionUpdate: (update) => this.#onConnectionUpdate(generation, update),
-      onHandshakeRejected: (response) =>
-        this.#onHandshakeRejected(generation, sock, response),
+      onHandshakeRejected: (response) => this.#onHandshakeRejected(generation, sock, response),
     });
 
-    const waitingForCode =
-      this.#pairing && this.#pairingIntent.method === "pairing";
+    const waitingForCode = this.#pairing && this.#pairingIntent.method === "pairing";
     this.#transition(this.#pairing ? S.WAITING_FOR_QR : S.STARTING, {
       reason,
       detail: this.#pairing
@@ -632,8 +671,8 @@ export class WhatsAppSession {
       viaProxy && (status === 407 || status === 401)
         ? `The proxy at ${this.#proxyLabel} rejected the username or password (HTTP ${status}).`
         : viaProxy
-        ? `The proxy at ${this.#proxyLabel} refused to connect to WhatsApp (HTTP ${status}).`
-        : `WhatsApp refused the connection (HTTP ${status}).`;
+          ? `The proxy at ${this.#proxyLabel} refused to connect to WhatsApp (HTTP ${status}).`
+          : `WhatsApp refused the connection (HTTP ${status}).`;
 
     this.log.error(`[Session] handshake rejected with HTTP ${status} — ${detail}`);
 
@@ -732,11 +771,7 @@ export class WhatsAppSession {
   async #onQr(qr) {
     // Pair-device readiness. In pairing-code mode the QR must not be shown;
     // requestPairingCode waits for this stanza (or queues until it arrives).
-    if (
-      this.#pairing &&
-      this.#pairingIntent.method === "pairing" &&
-      this.#pairingIntent.phone
-    ) {
+    if (this.#pairing && this.#pairingIntent.method === "pairing" && this.#pairingIntent.phone) {
       await this.#requestPairingCode();
       return;
     }
@@ -779,18 +814,14 @@ export class WhatsAppSession {
         this.#pairingCode = String(raw || "").replace(/\s|-/g, "");
         this.#transition(S.WAITING_FOR_QR, {
           reason: "pairing_code",
-          detail:
-            "Enter the code in WhatsApp → Linked devices → Link with phone number.",
+          detail: "Enter the code in WhatsApp → Linked devices → Link with phone number.",
         });
         this.emitEvent("pairing_code", {
           code: this.#pairingCode,
           phone,
         });
       } catch (error) {
-        this.log.error(
-          { err: error?.message },
-          "[Session] pairing code request failed"
-        );
+        this.log.error({ err: error?.message }, "[Session] pairing code request failed");
         if (!this.#pairing || this.#shuttingDown) return;
         this.#transition(S.ERROR, {
           reason: "pairing_failed",
@@ -822,9 +853,7 @@ export class WhatsAppSession {
   async #onClose(lastDisconnect) {
     const statusCode = lastDisconnect?.error?.output?.statusCode;
     const reasonText =
-      lastDisconnect?.error?.output?.payload?.error ||
-      lastDisconnect?.error?.message ||
-      "Unknown";
+      lastDisconnect?.error?.output?.payload?.error || lastDisconnect?.error?.message || "Unknown";
 
     this.#lastDisconnect = { statusCode: statusCode ?? null, reason: reasonText, at: Date.now() };
     const closedSocket = this.#socket;
@@ -850,7 +879,7 @@ export class WhatsAppSession {
 
     this.log.warn(
       `[Session] Connection closed (${statusCode ?? "no status"}: ${reasonText}) — ${verdict.label}` +
-        (this.#proxyLabel ? ` via ${this.#proxyLabel}` : "")
+        (this.#proxyLabel ? ` via ${this.#proxyLabel}` : ""),
     );
 
     if (this.#shuttingDown) return;
@@ -868,7 +897,9 @@ export class WhatsAppSession {
     if (verdict.terminal) {
       this.#clearQr();
       this.#pairing = false;
-      const codeInfo = this.#lastDisconnect?.statusCode ? ` (${this.#lastDisconnect.statusCode}: ${this.#lastDisconnect.reason})` : "";
+      const codeInfo = this.#lastDisconnect?.statusCode
+        ? ` (${this.#lastDisconnect.statusCode}: ${this.#lastDisconnect.reason})`
+        : "";
       return this.#transition(S.DISCONNECTED, {
         reason: verdict.reason,
         detail: `${verdict.detail || ""}${codeInfo}`.trim(),
@@ -880,7 +911,9 @@ export class WhatsAppSession {
     if (this.#pairing && !verdict.restartRequired) {
       this.#pairing = false;
       this.#clearQr();
-      const codeInfo = this.#lastDisconnect?.statusCode ? ` (${this.#lastDisconnect.statusCode}: ${this.#lastDisconnect.reason})` : "";
+      const codeInfo = this.#lastDisconnect?.statusCode
+        ? ` (${this.#lastDisconnect.statusCode}: ${this.#lastDisconnect.reason})`
+        : "";
       return this.#transition(S.DISCONNECTED, {
         reason: "pairing_cancelled",
         detail: `The pairing attempt ended before the code was scanned${codeInfo}. Start a session to try again.`,
@@ -914,6 +947,12 @@ export class WhatsAppSession {
     this.#clearQr();
     this.#cancelRetry();
     this.#attempt = 0;
+    this.#stopJobs();
+    try {
+      this.clearDirectory?.();
+    } catch (error) {
+      this.log.warn({ err: error }, "[Session] failed to clear WhatsApp directory after logout");
+    }
     this.#transition(S.LOGGED_OUT, { reason: verdict.reason, detail: verdict.detail });
   }
 
@@ -937,10 +976,12 @@ export class WhatsAppSession {
 
     if (this.#attempt >= this.retryDelaysMs.length) {
       this.log.error(
-        `[Session] ${this.retryDelaysMs.length} reconnect attempts failed. Levix stays up; start the session again from the panel.`
+        `[Session] ${this.retryDelaysMs.length} reconnect attempts failed. Levix stays up; start the session again from the panel.`,
       );
       this.#clearQr();
-      const codeInfo = this.#lastDisconnect?.statusCode ? ` (${this.#lastDisconnect.statusCode}: ${this.#lastDisconnect.reason})` : "";
+      const codeInfo = this.#lastDisconnect?.statusCode
+        ? ` (${this.#lastDisconnect.statusCode}: ${this.#lastDisconnect.reason})`
+        : "";
       return this.#transition(S.RETRY_EXHAUSTED, {
         reason: "retry_exhausted",
         detail: `Gave up after ${this.retryDelaysMs.length} attempts${codeInfo}. Start the session to try again.`,
@@ -952,10 +993,12 @@ export class WhatsAppSession {
     this.#nextRetryAt = Date.now() + delayMs;
 
     this.log.warn(
-      `[Session] Reconnecting in ${Math.round(delayMs / 1000)}s (attempt ${this.#attempt}/${this.retryDelaysMs.length})`
+      `[Session] Reconnecting in ${Math.round(delayMs / 1000)}s (attempt ${this.#attempt}/${this.retryDelaysMs.length})`,
     );
 
-    const codeInfo = this.#lastDisconnect?.statusCode ? ` (${this.#lastDisconnect.statusCode}: ${this.#lastDisconnect.reason})` : "";
+    const codeInfo = this.#lastDisconnect?.statusCode
+      ? ` (${this.#lastDisconnect.statusCode}: ${this.#lastDisconnect.reason})`
+      : "";
     this.#transition(S.RECONNECTING, {
       reason: verdict.reason,
       detail: