@leg3ndy/otto-bridge 0.6.1 → 0.6.3

package/README.md

@@ -33,10 +33,10 @@ Enquanto o pacote nao estiver publicado, voce pode gerar um tarball local:
 
 ```bash
 npm pack
-npm install -g ./leg3ndy-otto-bridge-0.6.1.tgz
+npm install -g ./leg3ndy-otto-bridge-0.6.3.tgz
 ```
 
-No `0.6.1`, `playwright` deixa de ser opcional no `otto-bridge`. O primeiro `npm install -g @leg3ndy/otto-bridge` pode demorar mais porque instala o browser persistente usado pelo WhatsApp Web e pelos fluxos web em background do bridge.
+No `0.6.3`, `playwright` deixa de ser opcional no `otto-bridge`. O primeiro `npm install -g @leg3ndy/otto-bridge` pode demorar mais porque instala o browser persistente usado pelo WhatsApp Web e pelos fluxos web em background do bridge.
 
 ## Publicacao
 
@@ -106,7 +106,7 @@ otto-bridge run --executor clawd-cursor --clawd-url http://127.0.0.1:3847
 
 ### WhatsApp Web em background
 
-Fluxo recomendado no `0.6.1`:
+Fluxo recomendado no `0.6.3`:
 
 ```bash
 otto-bridge extensions --install whatsappweb
@@ -116,6 +116,12 @@ otto-bridge extensions --status whatsappweb
 
 O setup agora abre o login do WhatsApp Web em um browser persistente do proprio bridge. Depois do QR code, o Otto usa a sessao local em background, sem depender de aba visivel no Safari.
 
+Contrato do `0.6.3`:
+
+- `otto-bridge extensions --setup whatsappweb`: autentica a sessao uma vez
+- `otto-bridge run`: mantem o browser persistente do WhatsApp vivo em background enquanto o runtime estiver ativo
+- ao parar o `otto-bridge run`: o browser em background e desligado, mas a sessao local fica lembrada para o proximo boot
+
 ### Ver estado local
 
 ```bash

package/dist/executors/native_macos.js

@@ -970,9 +970,13 @@ export class NativeMacOSJobExecutor {
     lastVisualTargetDescription = null;
     lastVisualTargetApp = null;
     whatsappBackgroundBrowser = null;
+    whatsappRuntimeMonitor = null;
     constructor(bridgeConfig) {
         this.bridgeConfig = bridgeConfig;
     }
+    async start() {
+        await this.ensureManagedBackgroundServices();
+    }
     async run(job, reporter) {
         if (process.platform !== "darwin") {
             throw new Error("The native-macos executor only runs on macOS");
@@ -1481,7 +1485,6 @@ export class NativeMacOSJobExecutor {
             await reporter.completed(resultPayload);
         }
         finally {
-            await this.closeWhatsAppBackgroundBrowser();
             this.cancelledJobs.delete(job.job_id);
         }
     }
@@ -1492,6 +1495,14 @@ export class NativeMacOSJobExecutor {
             this.activeChild = null;
         }
     }
+    async close() {
+        if (this.whatsappRuntimeMonitor) {
+            clearInterval(this.whatsappRuntimeMonitor);
+            this.whatsappRuntimeMonitor = null;
+        }
+        await this.syncWhatsAppRuntimeDetached();
+        await this.closeWhatsAppBackgroundBrowser();
+    }
     assertNotCancelled(jobId) {
         if (this.cancelledJobs.has(jobId)) {
             throw new JobCancelledError(jobId);
@@ -2115,16 +2126,32 @@ end repeat
             activate,
         };
     }
-    async syncWhatsAppExtensionState(status, notes) {
+    async syncWhatsAppExtensionState(status, notes, options) {
         const current = await loadManagedBridgeExtensionState(WHATSAPP_WEB_EXTENSION_SLUG).catch(() => null);
         if (!current) {
             return;
         }
+        const nowIso = new Date().toISOString();
         await saveManagedBridgeExtensionState(WHATSAPP_WEB_EXTENSION_SLUG, {
             ...current,
             status,
             notes,
-            lastStatusCheckAt: new Date().toISOString(),
+            runtimeAttached: options?.runtimeAttached ?? current.runtimeAttached,
+            lastRuntimeHeartbeatAt: options?.runtimeAttached !== undefined
+                ? nowIso
+                : current.lastRuntimeHeartbeatAt,
+            lastStatusCheckAt: nowIso,
+        }).catch(() => undefined);
+    }
+    async syncWhatsAppRuntimeDetached() {
+        const current = await loadManagedBridgeExtensionState(WHATSAPP_WEB_EXTENSION_SLUG).catch(() => null);
+        if (!current) {
+            return;
+        }
+        await saveManagedBridgeExtensionState(WHATSAPP_WEB_EXTENSION_SLUG, {
+            ...current,
+            runtimeAttached: false,
+            lastRuntimeHeartbeatAt: new Date().toISOString(),
         }).catch(() => undefined);
     }
     async getWhatsAppBackgroundBrowser() {
@@ -2191,9 +2218,9 @@ return {
         const backgroundBrowser = await this.getWhatsAppBackgroundBrowser().catch(() => null);
         if (backgroundBrowser) {
             try {
-                const state = await backgroundBrowser.getSessionState();
+                const state = await backgroundBrowser.waitForStableSessionState();
                 if (state.connected) {
-                    await this.syncWhatsAppExtensionState("connected", "Sessao local do WhatsApp Web pronta para uso no browser em background.");
+                    await this.syncWhatsAppExtensionState("connected", "Sessao local do WhatsApp Web pronta para uso no browser em background.", { runtimeAttached: true });
                     return;
                 }
                 const disconnectedStatus = currentState.status === "connected" || currentState.status === "session_expired"
@@ -2201,7 +2228,8 @@ return {
                     : "waiting_login";
                 await this.syncWhatsAppExtensionState(disconnectedStatus, state.qrVisible
                     ? "QR code visivel no browser persistente. Escaneie com o celular para concluir o login."
-                    : "Browser persistente do WhatsApp Web aberto, mas a sessao ainda nao esta pronta.");
+                    : "Browser persistente do WhatsApp Web aberto, mas a sessao ainda nao esta pronta.", { runtimeAttached: false });
+                await this.closeWhatsAppBackgroundBrowser();
                 if (disconnectedStatus === "session_expired") {
                     throw new Error("A sessao do WhatsApp Web expirou nesta maquina. Rode `otto-bridge extensions --setup whatsappweb` para fazer login de novo e depois `otto-bridge extensions --status whatsappweb`.");
                 }
@@ -2261,7 +2289,49 @@ return {
             }
             throw new Error("WhatsApp Web ainda nao esta conectado nesta maquina. Rode `otto-bridge extensions --setup whatsappweb`, escaneie o QR code e depois `otto-bridge extensions --status whatsappweb`.");
         }
-        await this.syncWhatsAppExtensionState("connected", "Sessao local do WhatsApp Web pronta para uso.");
+        await this.syncWhatsAppExtensionState("connected", "Sessao local do WhatsApp Web pronta para uso.", { runtimeAttached: false });
+    }
+    async ensureManagedBackgroundServices() {
+        if (!this.hasInstalledBridgeExtension(WHATSAPP_WEB_EXTENSION_SLUG)) {
+            return;
+        }
+        if (!this.whatsappRuntimeMonitor) {
+            this.whatsappRuntimeMonitor = setInterval(() => {
+                void this.refreshWhatsAppBackgroundRuntime();
+            }, 60_000);
+        }
+        await this.refreshWhatsAppBackgroundRuntime();
+    }
+    async refreshWhatsAppBackgroundRuntime() {
+        const currentState = await loadManagedBridgeExtensionState(WHATSAPP_WEB_EXTENSION_SLUG).catch(() => null);
+        if (!currentState) {
+            return;
+        }
+        if (currentState.status !== "connected") {
+            await this.syncWhatsAppRuntimeDetached();
+            await this.closeWhatsAppBackgroundBrowser();
+            return;
+        }
+        const backgroundBrowser = await this.getWhatsAppBackgroundBrowser().catch(() => null);
+        if (!backgroundBrowser) {
+            return;
+        }
+        try {
+            const state = await backgroundBrowser.waitForStableSessionState({ timeoutMs: 12_000 });
+            if (state.connected) {
+                await this.syncWhatsAppExtensionState("connected", "Sessao local do WhatsApp Web mantida em background enquanto `otto-bridge run` estiver ativo.", { runtimeAttached: true });
+                return;
+            }
+            await this.syncWhatsAppExtensionState("session_expired", state.qrVisible
+                ? "A sessao do WhatsApp Web expirou durante o runtime. Rode `otto-bridge extensions --setup whatsappweb` para abrir o QR code novamente."
+                : "O browser persistente do WhatsApp Web nao confirmou uma sessao pronta durante o runtime.", { runtimeAttached: false });
+            await this.closeWhatsAppBackgroundBrowser();
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            await this.syncWhatsAppExtensionState("session_expired", detail || "Nao consegui manter a sessao do WhatsApp Web no runtime em background.", { runtimeAttached: false });
+            await this.closeWhatsAppBackgroundBrowser();
+        }
     }
     async selectWhatsAppConversation(contact) {
         const backgroundBrowser = await this.getWhatsAppBackgroundBrowser().catch(() => null);

package/dist/extensions.js

@@ -58,6 +58,8 @@ export async function buildInstalledManagedExtensionState(slug) {
         installedAt: existing?.installedAt || new Date().toISOString(),
         lastSetupAt: existing?.lastSetupAt,
         lastStatusCheckAt: existing?.lastStatusCheckAt,
+        runtimeAttached: existing?.runtimeAttached,
+        lastRuntimeHeartbeatAt: existing?.lastRuntimeHeartbeatAt,
         notes: existing?.notes,
     };
 }

package/dist/main.js

@@ -7,6 +7,8 @@ import { pairDevice } from "./pairing.js";
 import { BridgeRuntime } from "./runtime.js";
 import { detectWhatsAppBackgroundStatus, runWhatsAppBackgroundSetup, } from "./whatsapp_background.js";
 import { BRIDGE_PACKAGE_NAME, BRIDGE_VERSION, DEFAULT_PAIR_TIMEOUT_SECONDS, DEFAULT_POLL_INTERVAL_MS, } from "./types.js";
+const RUNTIME_STATUS_FRESHNESS_MS = 90_000;
+const UPDATE_RETRY_DELAYS_MS = [0, 8_000, 20_000];
 function parseArgs(argv) {
     const [maybeCommand, ...rest] = argv;
     if (maybeCommand === "--help" || maybeCommand === "-h") {
@@ -46,6 +48,49 @@ function numberOption(args, name) {
     const parsed = Number(value);
     return Number.isFinite(parsed) ? parsed : undefined;
 }
+function hasFreshRuntimeAttachment(state) {
+    if (!state?.runtimeAttached || !state.lastRuntimeHeartbeatAt) {
+        return false;
+    }
+    const lastHeartbeatAt = Date.parse(state.lastRuntimeHeartbeatAt);
+    return Number.isFinite(lastHeartbeatAt) && Date.now() - lastHeartbeatAt <= RUNTIME_STATUS_FRESHNESS_MS;
+}
+function parseSemverTuple(value) {
+    const text = String(value || "").trim().replace(/^[vV]/, "");
+    if (!text) {
+        return null;
+    }
+    const parts = text.split(".");
+    const parsed = [];
+    for (const part of parts) {
+        const match = part.match(/^(\d+)/);
+        if (!match) {
+            return null;
+        }
+        parsed.push(Number(match[1]));
+    }
+    return parsed.length > 0 ? parsed : null;
+}
+function compareSemver(left, right) {
+    const a = parseSemverTuple(left);
+    const b = parseSemverTuple(right);
+    if (!a && !b)
+        return 0;
+    if (!a)
+        return -1;
+    if (!b)
+        return 1;
+    const maxLength = Math.max(a.length, b.length);
+    for (let index = 0; index < maxLength; index += 1) {
+        const leftPart = a[index] ?? 0;
+        const rightPart = b[index] ?? 0;
+        if (leftPart < rightPart)
+            return -1;
+        if (leftPart > rightPart)
+            return 1;
+    }
+    return 0;
+}
 function resolveExecutorOverrides(args, current) {
     return resolveExecutorConfig({
         type: option(args, "executor") || process.env.OTTO_BRIDGE_EXECUTOR,
@@ -100,6 +145,75 @@ function runChildCommand(command, args) {
         });
     });
 }
+function runChildCommandCapture(command, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            stdio: ["ignore", "pipe", "pipe"],
+            env: process.env,
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout?.setEncoding("utf8");
+        child.stdout?.on("data", (chunk) => {
+            stdout += String(chunk || "");
+        });
+        child.stderr?.setEncoding("utf8");
+        child.stderr?.on("data", (chunk) => {
+            stderr += String(chunk || "");
+        });
+        child.on("error", (error) => {
+            reject(error);
+        });
+        child.on("exit", (code) => {
+            resolve({
+                stdout,
+                stderr,
+                code: code ?? 1,
+            });
+        });
+    });
+}
+async function resolvePublishedPackageVersion(tag) {
+    const command = process.platform === "win32" ? "npm.cmd" : "npm";
+    const result = await runChildCommandCapture(command, [
+        "view",
+        `${BRIDGE_PACKAGE_NAME}@${tag}`,
+        "version",
+        "--json",
+    ]).catch(() => null);
+    if (!result || result.code !== 0) {
+        return null;
+    }
+    const stdout = String(result.stdout || "").trim();
+    if (!stdout) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(stdout);
+        if (typeof parsed === "string" && parsed.trim()) {
+            return parsed.trim();
+        }
+    }
+    catch {
+        if (stdout && stdout !== "null") {
+            return stdout.replace(/^"|"$/g, "").trim() || null;
+        }
+    }
+    return null;
+}
+function isRetryableNpmUpdateFailure(detail) {
+    const normalized = String(detail || "").toLowerCase();
+    return [
+        "code etarget",
+        "no matching version found",
+        "notarget",
+        "code enoversions",
+        "package version that doesn't exist",
+    ].some((pattern) => normalized.includes(pattern));
+}
+async function delay(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
 async function openManagedExtensionSetup(slug) {
     const definition = getManagedBridgeExtensionDefinition(slug);
     if (process.platform !== "darwin") {
@@ -112,6 +226,12 @@ async function detectManagedWhatsAppWebStatus() {
 }
 async function detectManagedExtensionStatus(slug, currentState) {
     if (slug === "whatsappweb") {
+        if (hasFreshRuntimeAttachment(currentState)) {
+            return {
+                status: "connected",
+                notes: currentState?.notes || "Sessao local do WhatsApp Web mantida em background enquanto `otto-bridge run` estiver ativo.",
+            };
+        }
         const detected = await detectManagedWhatsAppWebStatus();
         const shouldMarkExpired = (detected.status === "waiting_login"
             && (currentState?.status === "connected" || currentState?.status === "session_expired"));
@@ -161,7 +281,31 @@ async function runRuntimeCommand(args) {
         executor: resolveExecutorOverrides(args, config.executor),
     };
     const runtime = new BridgeRuntime(runtimeConfig);
-    await runtime.start();
+    let stopping = false;
+    const shutdown = async (signal) => {
+        if (stopping) {
+            return;
+        }
+        stopping = true;
+        console.log(`[otto-bridge] shutting down runtime after ${signal}`);
+        await runtime.stop().catch(() => undefined);
+    };
+    const handleSigint = () => {
+        void shutdown("SIGINT");
+    };
+    const handleSigterm = () => {
+        void shutdown("SIGTERM");
+    };
+    process.once("SIGINT", handleSigint);
+    process.once("SIGTERM", handleSigterm);
+    try {
+        await runtime.start();
+    }
+    finally {
+        process.off("SIGINT", handleSigint);
+        process.off("SIGTERM", handleSigterm);
+        await runtime.stop().catch(() => undefined);
+    }
 }
 async function runStatusCommand() {
     const config = await loadBridgeConfig();
@@ -252,6 +396,7 @@ async function runExtensionsCommand(args) {
         };
         await saveManagedBridgeExtensionState(slug, {
             ...baseState,
+            runtimeAttached: false,
             notes: `Setup iniciado para ${currentState.displayName}. Aguarde o login no browser persistente e depois rode \`otto-bridge extensions --status ${slug}\`.`,
         });
         if (slug === "whatsappweb") {
@@ -263,6 +408,7 @@ async function runExtensionsCommand(args) {
                 status: detected.status,
                 notes: detected.notes,
                 lastStatusCheckAt: new Date().toISOString(),
+                runtimeAttached: false,
             });
             console.log(`[otto-bridge] ${slug}: ${formatManagedBridgeExtensionStatus(detected.status)}`);
             if (detected.notes) {
@@ -293,6 +439,7 @@ async function runExtensionsCommand(args) {
             ...currentState,
             status: detected.status,
             lastStatusCheckAt: new Date().toISOString(),
+            runtimeAttached: hasFreshRuntimeAttachment(currentState) && detected.status === "connected",
             notes: detected.notes || currentState.notes,
         };
         await saveManagedBridgeExtensionState(slug, nextState);
@@ -344,20 +491,63 @@ async function runUnpairCommand() {
 }
 async function runUpdateCommand(args) {
     const tag = option(args, "tag") || "latest";
-    const packageSpec = `${BRIDGE_PACKAGE_NAME}@${tag}`;
+    const publishedVersion = await resolvePublishedPackageVersion(tag);
+    if (publishedVersion && compareSemver(publishedVersion, BRIDGE_VERSION) <= 0) {
+        console.log(`[otto-bridge] current=${BRIDGE_VERSION}`);
+        console.log(`[otto-bridge] latest published=${publishedVersion}`);
+        console.log("[otto-bridge] nenhuma atualizacao mais nova publicada no npm no momento");
+        return;
+    }
+    const packageSpec = `${BRIDGE_PACKAGE_NAME}@${publishedVersion || tag}`;
     const command = process.platform === "win32" ? "npm.cmd" : "npm";
-    const commandArgs = ["install", "-g", packageSpec];
+    const commandArgs = ["install", "-g", packageSpec, "--prefer-online"];
     const commandString = `${command} ${commandArgs.join(" ")}`;
     if (args.options.has("dry-run") || args.options.has("check")) {
         console.log(`[otto-bridge] current=${BRIDGE_VERSION}`);
+        if (publishedVersion) {
+            console.log(`[otto-bridge] target=${publishedVersion}`);
+        }
         console.log(`[otto-bridge] update command: ${commandString}`);
         return;
     }
     console.log(`[otto-bridge] current=${BRIDGE_VERSION}`);
+    if (publishedVersion) {
+        console.log(`[otto-bridge] target=${publishedVersion}`);
+    }
     console.log(`[otto-bridge] updating with: ${commandString}`);
-    await runChildCommand(command, commandArgs);
-    console.log("[otto-bridge] update completed");
-    console.log("[otto-bridge] run `otto-bridge version` to confirm the installed version");
+    let lastFailureDetail = "";
+    for (let attemptIndex = 0; attemptIndex < UPDATE_RETRY_DELAYS_MS.length; attemptIndex += 1) {
+        const waitMs = UPDATE_RETRY_DELAYS_MS[attemptIndex];
+        if (waitMs > 0) {
+            console.log(`[otto-bridge] aguardando ${Math.round(waitMs / 1000)}s para tentar novamente...`);
+            await delay(waitMs);
+        }
+        const result = await runChildCommandCapture(command, commandArgs).catch((error) => ({
+            stdout: "",
+            stderr: error instanceof Error ? error.message : String(error),
+            code: 1,
+        }));
+        if (result.stdout.trim()) {
+            process.stdout.write(result.stdout);
+        }
+        if (result.stderr.trim()) {
+            process.stderr.write(result.stderr);
+        }
+        if (result.code === 0) {
+            console.log("[otto-bridge] update completed");
+            console.log("[otto-bridge] run `otto-bridge version` to confirm the installed version");
+            return;
+        }
+        lastFailureDetail = `${command} exited with code ${result.code}\n${result.stderr || result.stdout}`.trim();
+        const retryable = isRetryableNpmUpdateFailure(lastFailureDetail);
+        const hasNextAttempt = attemptIndex < UPDATE_RETRY_DELAYS_MS.length - 1;
+        if (!retryable || !hasNextAttempt) {
+            break;
+        }
+        console.log("[otto-bridge] A release ainda pode estar propagando no npm. Vou tentar novamente com cache online.");
+    }
+    const hintSpec = `${BRIDGE_PACKAGE_NAME}@${publishedVersion || tag}`;
+    throw new Error(`${lastFailureDetail}\n[otto-bridge] Se a release acabou de ser publicada, isso costuma ser propagacao do npm.\n[otto-bridge] Fallback manual: npm install -g ${hintSpec} --prefer-online`);
 }
 async function main() {
     const args = parseArgs(process.argv.slice(2));

package/dist/runtime.js

@@ -73,6 +73,9 @@ export class BridgeRuntime {
     reconnectDelayMs = DEFAULT_RECONNECT_BASE_DELAY_MS;
     executor;
     lastBridgeReleaseNoticeKey = null;
+    activeSocket = null;
+    stopped = false;
+    started = false;
     pendingConfirmations = new Map();
     activeCancels = new Map();
     constructor(config, executor) {
@@ -136,23 +139,62 @@ export class BridgeRuntime {
         }));
     }
     async start() {
+        if (!this.started) {
+            this.started = true;
+            if (typeof this.executor.start === "function") {
+                await this.executor.start();
+            }
+        }
         console.log(`[otto-bridge] runtime start device=${this.config.deviceId}`);
-        while (true) {
+        while (!this.stopped) {
             try {
                 await this.connectOnce();
                 this.reconnectDelayMs = DEFAULT_RECONNECT_BASE_DELAY_MS;
             }
             catch (error) {
+                if (this.stopped) {
+                    break;
+                }
                 const message = error instanceof Error ? error.message : String(error);
                 console.error(`[otto-bridge] socket error: ${message}`);
             }
+            if (this.stopped) {
+                break;
+            }
             console.log(`[otto-bridge] reconnecting in ${this.reconnectDelayMs}ms`);
             await delay(this.reconnectDelayMs);
             this.reconnectDelayMs = Math.min(this.reconnectDelayMs * 2, DEFAULT_RECONNECT_MAX_DELAY_MS);
         }
     }
+    async stop() {
+        this.stopped = true;
+        for (const [jobId, cancel] of this.activeCancels.entries()) {
+            try {
+                await cancel();
+            }
+            catch {
+                // ignore shutdown cancellation errors
+            }
+            finally {
+                this.activeCancels.delete(jobId);
+            }
+        }
+        try {
+            this.activeSocket?.close();
+        }
+        catch {
+            // ignore socket close errors during shutdown
+        }
+        finally {
+            this.activeSocket = null;
+        }
+        if (typeof this.executor.close === "function") {
+            await this.executor.close();
+        }
+    }
     async connectOnce() {
         const socket = new WebSocket(this.config.wsUrl, ["device", this.config.deviceToken]);
+        this.activeSocket = socket;
         let heartbeatTimer = null;
         const stopHeartbeat = () => {
             if (heartbeatTimer) {
@@ -196,12 +238,14 @@ export class BridgeRuntime {
             socket.addEventListener("close", (event) => {
                 stopHeartbeat();
                 rejectPendingConfirmations(new Error("WebSocket closed while awaiting confirmation"));
+                this.activeSocket = null;
                 console.log(`[otto-bridge] socket closed code=${event.code}`);
                 resolve();
             });
             socket.addEventListener("error", () => {
                 stopHeartbeat();
                 rejectPendingConfirmations(new Error("WebSocket failed while awaiting confirmation"));
+                this.activeSocket = null;
                 try {
                     socket.close();
                 }

package/dist/types.js

@@ -1,5 +1,5 @@
 export const BRIDGE_CONFIG_VERSION = 1;
-export const BRIDGE_VERSION = "0.6.1";
+export const BRIDGE_VERSION = "0.6.3";
 export const BRIDGE_PACKAGE_NAME = "@leg3ndy/otto-bridge";
 export const DEFAULT_API_BASE_URL = "http://localhost:8000";
 export const DEFAULT_POLL_INTERVAL_MS = 3000;

package/dist/whatsapp_background.js

@@ -4,6 +4,9 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { getBridgeHomeDir } from "./config.js";
 export const WHATSAPP_WEB_URL = "https://web.whatsapp.com";
 const DEFAULT_SETUP_TIMEOUT_MS = 5 * 60 * 1000;
+const DEFAULT_SESSION_SETTLE_TIMEOUT_MS = 15_000;
+const DEFAULT_SESSION_POLL_INTERVAL_MS = 1_000;
+const DEFAULT_QR_STABILITY_WINDOW_MS = 4_000;
 function moduleDir() {
     return path.dirname(fileURLToPath(import.meta.url));
 }
@@ -158,7 +161,7 @@ export class WhatsAppBackgroundBrowser {
         };
     }
     async ensureReady() {
-        const state = await this.getSessionState();
+        const state = await this.waitForStableSessionState();
         if (state.connected) {
             return state;
         }
@@ -179,6 +182,33 @@ export class WhatsAppBackgroundBrowser {
         }
         return lastState || await this.getSessionState();
     }
+    async waitForStableSessionState(options) {
+        const timeoutMs = Math.max(2_000, Number(options?.timeoutMs || DEFAULT_SESSION_SETTLE_TIMEOUT_MS));
+        const pollIntervalMs = Math.max(250, Number(options?.pollIntervalMs || DEFAULT_SESSION_POLL_INTERVAL_MS));
+        const qrStabilityWindowMs = Math.max(pollIntervalMs, Number(options?.qrStabilityWindowMs || DEFAULT_QR_STABILITY_WINDOW_MS));
+        const deadline = Date.now() + timeoutMs;
+        let lastState = null;
+        let qrVisibleSince = null;
+        while (Date.now() < deadline) {
+            lastState = await this.getSessionState();
+            if (lastState.connected) {
+                return lastState;
+            }
+            if (lastState.qrVisible) {
+                if (qrVisibleSince === null) {
+                    qrVisibleSince = Date.now();
+                }
+                else if (Date.now() - qrVisibleSince >= qrStabilityWindowMs) {
+                    return lastState;
+                }
+            }
+            else {
+                qrVisibleSince = null;
+            }
+            await this.page?.waitForTimeout(pollIntervalMs);
+        }
+        return lastState || await this.getSessionState();
+    }
     async selectConversation(contact) {
         await this.ensureReady();
         const prepared = await this.withPage((page) => page.evaluate((query) => {
@@ -464,7 +494,7 @@ export async function detectWhatsAppBackgroundStatus() {
     }
     const browser = new WhatsAppBackgroundBrowser({ headless: true });
     try {
-        const state = await browser.getSessionState();
+        const state = await browser.waitForStableSessionState();
         return sessionStateToStatus(state);
     }
     catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leg3ndy/otto-bridge",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "private": false,
   "type": "module",
   "description": "Local companion for Otto Bridge device pairing and WebSocket runtime.",