The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
fix(dashboard): allow safe WhatsApp re-pairing after logout (#142439)
Gille13282fdac488
diff --git a/gateway/status.py b/gateway/status.pyindex 9d1a90b16c0..455da6f5099 100644--- a/gateway/status.py+++ b/gateway/status.py@@ -1513,27 +1513,6 @@ def remove_pid_file() -> None:_clear_running_pid_cache()-def _scoped_lock_record_is_stale(existing: dict[str, Any], existing_pid: Optional[int]) -> bool:- """True when a foreign scoped-lock record no longer names a live gateway: PID missing/dead,- start time changed (PID reuse), or the live process is not a gateway -- a readable cmdline says- so (also catches boot-time PID+start_time collisions; systemd spawns deterministically);- cmdline unreadable AND start_time unknown on either side => the lock record's own argv is the- only signal left. Stopped (SIGTSTP) processes look alive to _pid_exists; stale so --replace- works."""- if existing_pid is None or not _pid_exists(existing_pid):- return True- recorded_start = existing.get("start_time")- current_start = _get_process_start_time(existing_pid)- if _start_times_conflict(recorded_start, current_start):- return True- if not _looks_like_gateway_process(existing_pid):- if _read_process_cmdline(existing_pid) is not None:- return True- if None in (recorded_start, current_start) and not _record_looks_like_gateway(existing):- return True- return _process_is_stopped(existing_pid)--def _process_is_stopped(pid: int) -> bool:"""True for a stopped / tracing-stop state (T/t) in ``/proc/<pid>/status``."""with contextlib.suppress(OSError):@@ -1548,6 +1527,8 @@ def acquire_scoped_lock() -> tuple[bool, Optional[dict[str, Any]]]:"""Acquire a machine-local lock keyed by scope + identity (one Telegram token across homes).+ ``metadata={"owner_kind": "process"}`` allows a non-gateway owner such as+ a setup process. Its PID/start-time identity still gates stale recovery.Raises :class:`gateway.status_lock_dir.ScopedLockDirUnusable` (logged once per dir with the repair) when this token maynot use the lock dir at all."""lock_path = _get_scope_lock_path(scope, identity)@@ -1562,6 +1543,8 @@ def acquire_scoped_lock(def _acquire_scoped_lock_at(lock_path: Path, scope: str, identity: str, metadata: Optional[dict[str, Any]]) -> tuple[bool, Optional[dict[str, Any]]]:+ from gateway.status_scoped_locks import _scoped_lock_record_is_stale+make_user_dir(lock_path.parent, parents=True, exist_ok=True)# An existing lock this token may not read (left by an elevated gateway) must raise here:# ``_read_json_file`` would call it empty and O_EXCL "in use", a conflict with no holder.diff --git a/gateway/status_scoped_locks.py b/gateway/status_scoped_locks.pyindex e278aba6a78..bff555ecade 100644--- a/gateway/status_scoped_locks.py+++ b/gateway/status_scoped_locks.py@@ -1,15 +1,39 @@-"""Scoped-lock release, split from :mod:`gateway.status` (acquire stays there). One-way: this-module reads the status helpers through the module at call time (so tests that patch-``gateway.status`` keep steering them); :mod:`gateway.status` never imports it."""+"""Scoped-lock ownership and release, split from :mod:`gateway.status` (acquire stays there).++Helpers read status through the module at call time, preserving its patch seams.+The acquire path imports the ownership check lazily to avoid an import cycle.+"""from __future__ import annotationsimport contextlibimport os-from typing import Optional+from typing import Any, Optionalfrom gateway import status as _status+def _scoped_lock_record_is_stale(existing: dict[str, Any], existing_pid: Optional[int]) -> bool:+ """Recover dead/reused/stopped owners. Gateway locks also validate gateway argv.++ An explicitly process-owned reservation can belong to a dashboard or setup+ worker. Unknown identity stays reserved instead of guessing that it is dead.+ """+ if existing_pid is None or not _status._pid_exists(existing_pid):+ return True+ recorded_start = existing.get("start_time")+ current_start = _status._get_process_start_time(existing_pid)+ if _status._start_times_conflict(recorded_start, current_start):+ return True+ metadata = existing.get("metadata")+ process_owner = isinstance(metadata, dict) and metadata.get("owner_kind") == "process"+ if not process_owner and not _status._looks_like_gateway_process(existing_pid):+ if _status._read_process_cmdline(existing_pid) is not None:+ return True+ if None in (recorded_start, current_start) and not _status._record_looks_like_gateway(existing):+ return True+ return _status._process_is_stopped(existing_pid)++def release_scoped_lock(scope: str, identity: str) -> None:"""Release a scope lock owned by this PID. No start_time equality check: on-disk null vs a livefingerprint would wedge reconnects."""diff --git a/hermes_cli/web_models.py b/hermes_cli/web_models.pyindex b96151b370f..98e6887ab97 100644--- a/hermes_cli/web_models.py+++ b/hermes_cli/web_models.py@@ -76,6 +76,7 @@ class WhatsAppOnboardingStart(BaseModel):mode: Optional[str] = "bot"allowed_users: Optional[str] = ""profile: Optional[str] = None+ reset_session: bool = Falseclass WhatsAppOnboardingApply(BaseModel):mode: Optional[str] = Nonediff --git a/hermes_cli/web_routers/messaging.py b/hermes_cli/web_routers/messaging.pyindex c918b248db3..d29a32a5cf8 100644--- a/hermes_cli/web_routers/messaging.py+++ b/hermes_cli/web_routers/messaging.py@@ -27,6 +27,7 @@ from hermes_cli.config import OPTIONAL_ENV_VARS, get_env_pathfrom hermes_constants import get_process_hermes_homefrom hermes_cli.web_deps import LateState, latefrom hermes_cli.web_server_gateway import _restart_gateway_after+from hermes_cli.web_whatsapp_session import _backup_whatsapp_sessionfrom hermes_cli.web_server_messaging import (_TelegramOnboardingPairing, _WhatsAppOnboardingSession, _messaging_platform_catalog, _telegram_onboarding_error_message, _telegram_onboarding_lock, _telegram_onboarding_pairings, _whatsapp_onboarding_payload, _whatsapp_onboarding_sessions,)@@ -435,6 +436,7 @@ def _terminate_whatsapp_pairing(proc: subprocess.Popen | None) -> None:except Exception:with contextlib.suppress(Exception):proc.kill()+ proc.wait(timeout=3)def _fail_whatsapp_pairing(pairing_id: str, error: str, *, proc=None, unless=_WHATSAPP_ONBOARDING_TERMINAL_STATUSES) -> None:@@ -485,7 +487,8 @@ def _watch_whatsapp_pairing(pairing_id: str, proc: subprocess.Popen) -> None:record = _whatsapp_onboarding_sessions.get(pairing_id)if not record or record.proc is not proc:return- _apply_pairing_event(record, payload)+ if record.status not in {"cancelled", "expired"}:+ _apply_pairing_event(record, payload)returncode = proc.wait()except Exception as exc:_fail_whatsapp_pairing(pairing_id, str(exc), proc=proc)@@ -501,40 +504,71 @@ def _run_whatsapp_pairing(pairing_id: str, session_path: Path, mode: str) -> Nonwith _whatsapp_onboarding_lock:record = _whatsapp_onboarding_sessions.get(pairing_id)if not record or record.status in _WHATSAPP_ONBOARDING_TERMINAL_STATUSES:+ if record:+ _release_whatsapp_reservation(record)returnrecord.status = "installing"+ record.starting_process = Truetry:- proc = _spawn_whatsapp_pairing_process(session_path, mode)- except Exception as exc:- _fail_whatsapp_pairing(pairing_id, str(exc))+ try:+ proc = _spawn_whatsapp_pairing_process(session_path, mode)+ except Exception as exc:+ _fail_whatsapp_pairing(pairing_id, str(exc))+ return++ with _whatsapp_onboarding_lock:+ record.starting_process = False+ record.proc = proc+ if record.status in _WHATSAPP_ONBOARDING_TERMINAL_STATUSES:+ _terminate_whatsapp_pairing(proc)+ return+ record.status = "starting"++ _watch_whatsapp_pairing(pairing_id, proc)+ finally:+ with _whatsapp_onboarding_lock:+ record.starting_process = False+ _release_whatsapp_reservation(record)+++def _release_whatsapp_reservation(record: _WhatsAppOnboardingSession) -> None:+ """Call under the onboarding lock. A live writer keeps its reservation."""+ if not record.session_reserved or record.starting_process:+ return+ if record.proc is None and record.status not in _WHATSAPP_ONBOARDING_TERMINAL_STATUSES:+ return # A queued worker has not entered its startup section yet.+ if record.proc is not None and record.proc.poll() is None:return+ from gateway.status_scoped_locks import release_scoped_lock- with _whatsapp_onboarding_lock:- record = _whatsapp_onboarding_sessions.get(pairing_id)- if not record or record.status in _WHATSAPP_ONBOARDING_TERMINAL_STATUSES:- _terminate_whatsapp_pairing(proc)- return- record.proc = proc- record.status = "starting"+ release_scoped_lock("whatsapp-session", record.session_path)+ record.session_reserved = False+ if record.expiry_timer is not None:+ record.expiry_timer.cancel()- _watch_whatsapp_pairing(pairing_id, proc)++def _expire_whatsapp_pairing(record: _WhatsAppOnboardingSession) -> None:+ with _whatsapp_onboarding_lock:+ if record.status not in _WHATSAPP_ONBOARDING_TERMINAL_STATUSES or record.session_reserved:+ record.status = "expired"+ record.error = "WhatsApp QR setup expired. Start a new setup."+ _terminate_whatsapp_pairing(record.proc)+ _release_whatsapp_reservation(record)def _prune_whatsapp_onboarding_sessions() -> None:now = time.time()remove_ids: list[str] = []for pairing_id, record in _whatsapp_onboarding_sessions.items():+ _release_whatsapp_reservation(record)live = record.status not in _WHATSAPP_ONBOARDING_TERMINAL_STATUSESif live and record.proc is not None and record.proc.poll() is not None:record.status = "error"record.error = "WhatsApp pairing process exited before pairing completed."- live = False- if live and record.expires_at_ts <= now:- _terminate_whatsapp_pairing(record.proc)- record.status = "expired"- record.error = "WhatsApp QR setup expired. Start a new setup."- if record.status in _WHATSAPP_ONBOARDING_TERMINAL_STATUSES and record.expires_at_ts + 300 <= now:+ if record.expires_at_ts <= now:+ _expire_whatsapp_pairing(record)+ if record.status in _WHATSAPP_ONBOARDING_TERMINAL_STATUSES and not record.session_reserved and record.expires_at_ts + 300 <= now:remove_ids.append(pairing_id)for pairing_id in remove_ids:_whatsapp_onboarding_sessions.pop(pairing_id, None)@@ -555,28 +589,81 @@ def _register_whatsapp_session(session_path: Path, record) -> str:return pairing_id+def _reserve_whatsapp_session(record: _WhatsAppOnboardingSession) -> None:+ """Reserve before moving keys or launching a writer, including its queued start."""+ from gateway.status import acquire_scoped_lock++ busy = "WhatsApp is in use. Disable WhatsApp and restart the gateway, then try re-pairing again."+ for existing in _whatsapp_onboarding_sessions.values():+ if existing.session_path == record.session_path and (+ existing.status not in _WHATSAPP_ONBOARDING_TERMINAL_STATUSES+ or existing.session_reserved or existing.starting_process+ or (existing.proc is not None and existing.proc.poll() is None)+ ):+ raise HTTPException(status_code=409, detail="Another WhatsApp QR setup is still active. Cancel it or wait for it to stop before re-pairing.")+ acquired, previous = acquire_scoped_lock("whatsapp-session", record.session_path, metadata={"owner_kind": "process"})+ if not acquired or previous and previous.get("pid") == os.getpid():+ # Self-reacquisition is allowed for gateway reconnects. Reset must not+ # borrow or release a lock already held by this process.+ raise HTTPException(status_code=409, detail=busy)+ record.session_reserved = True+++def _launch_whatsapp_pairing(pairing_id: str, record: _WhatsAppOnboardingSession, session_path: Path) -> None:+ from agent.memory_provider import spawn_context_thread++ record.expiry_timer = threading.Timer(_WHATSAPP_ONBOARDING_TTL_SECONDS, _expire_whatsapp_pairing, args=(record,))+ record.expiry_timer.daemon = True+ launched = False+ try:+ record.expiry_timer.start()+ spawn_context_thread(_run_whatsapp_pairing, name="whatsapp-pairing",+ args=(pairing_id, session_path, record.mode)).start()+ launched = True+ finally:+ if not launched:+ record.status = "error"+ _release_whatsapp_reservation(record)++@router.post("/api/messaging/whatsapp/onboarding/start")-async def start_whatsapp_onboarding(body: WhatsAppOnboardingStart):+async def start_whatsapp_onboarding(body: WhatsAppOnboardingStart, profile: Optional[str] = None):mode = _normalize_whatsapp_onboarding_mode(body.mode)allowed_users = _normalize_whatsapp_allowed_users(body.allowed_users)- with _config_profile_scope(body.profile):+ target_profile = body.profile or profile+ with _config_profile_scope(target_profile), _whatsapp_onboarding_lock:+ _prune_whatsapp_onboarding_sessions()session_path = _whatsapp_session_path()+ if any(r.session_path == str(session_path) and r.session_reserved for r in _whatsapp_onboarding_sessions.values()):+ raise HTTPException(status_code=409, detail="Another WhatsApp QR setup is still active. Cancel it or wait for it to stop before re-pairing.")expires_at_ts = time.time() + _WHATSAPP_ONBOARDING_TTL_SECONDS- fields = dict(+ fields: dict[str, Any] = dict(proc=None, mode=mode, allowed_users=allowed_users, session_path=str(session_path),expires_at=datetime.fromtimestamp(expires_at_ts, UTC).isoformat().replace("+00:00", "Z"),- expires_at_ts=expires_at_ts, profile=body.profile,+ expires_at_ts=expires_at_ts, profile=target_profile,)- already_linked = (session_path / "creds.json").exists()+ already_linked = not body.reset_session and (session_path / "creds.json").exists()if already_linked: # creds on disk: report connected without pairingaccount_id, account_name, account_phone = _whatsapp_linked_account_from_session(session_path)fields.update(status="connected", account_id=account_id, account_name=account_name, account_phone=account_phone)- record = _WhatsAppOnboardingSession(**fields)- pairing_id = _register_whatsapp_session(session_path, record)- if not already_linked:- threading.Thread(target=_run_whatsapp_pairing, args=(pairing_id, session_path, mode), daemon=True).start()+ record = _WhatsAppOnboardingSession(**fields)+ if already_linked:+ pairing_id = _register_whatsapp_session(session_path, record)+ else:+ _reserve_whatsapp_session(record)+ launched = False+ try:+ if body.reset_session:+ _backup_whatsapp_session(session_path)+ pairing_id = _register_whatsapp_session(session_path, record)+ _launch_whatsapp_pairing(pairing_id, record, session_path)+ launched = True+ finally:+ if not launched:+ record.status = "error"+ _release_whatsapp_reservation(record)return _whatsapp_onboarding_payload(pairing_id, record)@@ -600,6 +687,7 @@ async def get_whatsapp_onboarding_status(pairing_id: str):@router.post("/api/messaging/whatsapp/onboarding/{pairing_id}/apply")async def apply_whatsapp_onboarding(pairing_id: str, body: WhatsAppOnboardingApply, profile: Optional[str] = None):+ await _wait_whatsapp_pairing_flush(pairing_id)with _whatsapp_onboarding_lock:record = _whatsapp_record_or_404(pairing_id)if record.status != "connected":@@ -623,19 +711,43 @@ async def apply_whatsapp_onboarding(pairing_id: str, body: WhatsAppOnboardingApp_write_platform_enabled("whatsapp", True)with _whatsapp_onboarding_lock:- _whatsapp_onboarding_sessions.pop(pairing_id, None)+ # A connected pair-only bridge may still be flushing credentials.+ # Retain it for reset's writer guard until that process has exited.+ if record.proc is None or record.proc.poll() is not None:+ _whatsapp_onboarding_sessions.pop(pairing_id, None)restart_result = _restart_gateway_after_whatsapp_onboarding(effective_profile)return {"ok": True, "platform": "whatsapp", "needs_restart": not restart_result["restart_started"], **restart_result}+async def _wait_whatsapp_pairing_flush(pairing_id: str) -> None:+ with _whatsapp_onboarding_lock:+ record = _whatsapp_record_or_404(pairing_id)+ if record.status != "connected":+ raise HTTPException(status_code=409, detail="WhatsApp setup is not connected yet.")+ if record.session_reserved and record.proc is not None:+ try:+ await asyncio.to_thread(record.proc.wait, timeout=3)+ except subprocess.TimeoutExpired as exc:+ raise HTTPException(status_code=409, detail="WhatsApp is still saving its linked device. Wait a moment and try Save and restart again.") from exc+ with _whatsapp_onboarding_lock:+ _release_whatsapp_reservation(record)+ if record.session_reserved:+ raise HTTPException(status_code=409, detail="WhatsApp is still finishing pairing. Wait a moment and try Save and restart again.")++@router.delete("/api/messaging/whatsapp/onboarding/{pairing_id}")async def cancel_whatsapp_onboarding(pairing_id: str):with _whatsapp_onboarding_lock:- record = _whatsapp_onboarding_sessions.pop(pairing_id, None)- if record:- record.status = "cancelled"- _terminate_whatsapp_pairing(record.proc)+ record = _whatsapp_onboarding_sessions.get(pairing_id)+ if record:+ record.status = "cancelled"+ _terminate_whatsapp_pairing(record.proc)+ _release_whatsapp_reservation(record)+ # Keep a cancelled worker visible until its process launch has+ # finished. It may still be opening the session directory.+ if not record.starting_process and (record.proc is None or record.proc.poll() is not None):+ _whatsapp_onboarding_sessions.pop(pairing_id, None)return {"ok": True}diff --git a/hermes_cli/web_server_messaging.py b/hermes_cli/web_server_messaging.pyindex 584674b1758..bd72b5ba884 100644--- a/hermes_cli/web_server_messaging.py+++ b/hermes_cli/web_server_messaging.py@@ -199,6 +199,9 @@ class _WhatsAppOnboardingSession:account_name: str | None = Noneaccount_phone: str | None = Noneerror: str | None = None+ starting_process: bool = False+ session_reserved: bool = False+ expiry_timer: threading.Timer | None = None_whatsapp_onboarding_sessions: dict[str, _WhatsAppOnboardingSession] = {}diff --git a/hermes_cli/web_whatsapp_session.py b/hermes_cli/web_whatsapp_session.pynew file mode 100644index 00000000000..f01f29e6859--- /dev/null+++ b/hermes_cli/web_whatsapp_session.py@@ -0,0 +1,57 @@+"""Preserve WhatsApp authentication state before dashboard re-pairing."""++import tempfile+from datetime import UTC, datetime+from pathlib import Path++from fastapi import HTTPException+++def _assert_whatsapp_bridge_stopped(session_path: Path) -> None:+ from gateway.status import _pid_exists, get_process_start_time++ pid_file = session_path / "bridge.pid"+ if not pid_file.exists():+ return+ unknown = "Cannot verify the WhatsApp bridge is stopped. Check its bridge.pid before re-pairing."+ try:+ lines = pid_file.read_text(encoding="utf-8-sig").splitlines()+ pid = int(lines[0])+ if pid <= 0:+ raise ValueError("invalid bridge PID")+ except (OSError, ValueError, IndexError) as exc:+ raise HTTPException(status_code=409, detail=unknown) from exc+ if not _pid_exists(pid):+ return+ try:+ recorded_start = int(lines[1])+ if recorded_start <= 0:+ raise ValueError("invalid bridge start time")+ except (ValueError, IndexError) as exc:+ raise HTTPException(status_code=409, detail=unknown) from exc+ current_start = get_process_start_time(pid)+ if current_start is None:+ raise HTTPException(status_code=409, detail=unknown)+ if current_start == recorded_start:+ raise HTTPException(status_code=409, detail="The WhatsApp bridge is still running. Stop it before re-pairing.")+ # Both fingerprints are available and differ. This is a recycled PID,+ # not evidence that the old bridge still owns the session.+++def _backup_whatsapp_session(session_path: Path) -> None:+ """Called while onboarding owns the session reservation. Never delete keys."""+ _assert_whatsapp_bridge_stopped(session_path)+ if session_path.is_symlink():+ raise HTTPException(status_code=409, detail="The WhatsApp session is a symbolic link. Back it up manually before re-pairing.")+ backup = None+ try:+ if session_path.exists():+ stamp = datetime.now(UTC).strftime("%Y%m%dT%H%M%SZ")+ backup = Path(tempfile.mkdtemp(prefix=f"session-backup-{stamp}-", dir=session_path.parent)) / "session"+ session_path.rename(backup)+ session_path.mkdir(mode=0o700)+ except OSError as exc:+ detail = f"Could not back up the WhatsApp session: {exc}. Pairing was not started."+ if backup is not None and backup.exists():+ detail += f" The previous session is preserved at {backup}."+ raise HTTPException(status_code=500, detail=detail) from excdiff --git a/tests/gateway/test_scoped_process_reservations.py b/tests/gateway/test_scoped_process_reservations.pynew file mode 100644index 00000000000..f3197f04ea9--- /dev/null+++ b/tests/gateway/test_scoped_process_reservations.py@@ -0,0 +1,39 @@+"""Non-gateway setup processes can reserve an existing adapter lock."""++import os++from gateway import status+from gateway.status_scoped_locks import _scoped_lock_record_is_stale+++def test_live_process_owner_does_not_need_gateway_argv():+ record = status._build_pid_record()+ record["metadata"] = {"owner_kind": "process"}+ assert not _scoped_lock_record_is_stale(record, os.getpid())+++def test_default_gateway_owner_still_requires_gateway_argv():+ record = status._build_pid_record()+ assert _scoped_lock_record_is_stale(record, os.getpid())+++def test_recycled_process_owner_is_stale():+ record = status._build_pid_record()+ assert record["start_time"] is not None+ record["start_time"] -= 10+ record["metadata"] = {"owner_kind": "process"}+ assert _scoped_lock_record_is_stale(record, os.getpid())+++def test_unknown_live_process_identity_remains_reserved(monkeypatch):+ record = status._build_pid_record()+ record["start_time"] = None+ record["metadata"] = {"owner_kind": "process"}+ monkeypatch.setattr(status, "_get_process_start_time", lambda pid: None)+ assert not _scoped_lock_record_is_stale(record, os.getpid())+++def test_invalid_metadata_does_not_bypass_gateway_validation():+ record = status._build_pid_record()+ record["metadata"] = ["process"]+ assert _scoped_lock_record_is_stale(record, os.getpid())diff --git a/tests/hermes_cli/test_whatsapp_dashboard_repair.py b/tests/hermes_cli/test_whatsapp_dashboard_repair.pynew file mode 100644index 00000000000..146a5996a1b--- /dev/null+++ b/tests/hermes_cli/test_whatsapp_dashboard_repair.py@@ -0,0 +1,443 @@+"""Dashboard recovery must bypass revoked credentials without losing them."""++import asyncio+import json+import os+import re+import subprocess+import sys+import time+from pathlib import Path+from subprocess import Popen+from types import SimpleNamespace+from typing import cast++import pytest+from fastapi import HTTPException++from hermes_cli import web_models, web_server_messaging+from hermes_cli.web_routers import messaging+++def pairing(tmp_path, monkeypatch):+ from gateway import status++ home = tmp_path / "home"+ home.mkdir()+ monkeypatch.setenv("HERMES_HOME", str(home))+ monkeypatch.setattr(Path, "home", lambda: tmp_path)+ monkeypatch.setenv("HERMES_GATEWAY_LOCK_DIR", str(tmp_path / "locks"))+ messaging._whatsapp_onboarding_sessions.clear()+ session = home / "platforms" / "whatsapp" / "session"+ session.mkdir(parents=True)+ creds = '{"me":{"id":"15550001111:[email protected]"},"registered":true}'+ (session / "creds.json").write_text(creds, encoding="utf-8")+ (session / "app-state.json").write_text("preserve", encoding="utf-8")+ starts = []+ workers = []+ timers = []+ real_thread = messaging.threading.Thread++ class Timer:+ def __init__(self, interval, function, args):+ self.function, self.args = function, args+ self.cancelled = False++ def start(self):+ timers.append(self)++ def cancel(self):+ self.cancelled = True++ def fire(self):+ if not self.cancelled:+ self.function(*self.args)++ class Thread:+ def __init__(self, *, target, args, daemon, kwargs=None, name=None):+ self.args = args+ self.target = target++ def start(self):+ starts.append(self.args)+ workers.append(self)++ monkeypatch.setattr(messaging.threading, "Thread", Thread)+ monkeypatch.setattr(messaging.threading, "Timer", Timer)++ def start(**kwargs):+ return asyncio.run(messaging.start_whatsapp_onboarding(web_models.WhatsAppOnboardingStart(**kwargs)))++ def gateway_can_acquire():+ from hermes_cli._subprocess_compat import windows_hide_flags++ output = tmp_path / "lock-probe.txt"+ code = "from gateway.status import acquire_scoped_lock; import sys; print(acquire_scoped_lock('whatsapp-session', sys.argv[1])[0])"+ with output.open("w", encoding="utf-8") as stream:+ subprocess.run([sys.executable, "-c", code, str(session)], stdout=stream, stderr=subprocess.STDOUT,+ timeout=20, check=True, creationflags=windows_hide_flags())+ return output.read_text(encoding="utf-8").strip() == "True"++ yield SimpleNamespace(home=home, session=session, creds=creds, starts=starts, workers=workers, timers=timers,+ start=start, gateway_can_acquire=gateway_can_acquire, real_thread=real_thread)+ from gateway.status_scoped_locks import release_scoped_lock++ for record in messaging._whatsapp_onboarding_sessions.values():+ timer = record.expiry_timer+ if timer is not None:+ timer.cancel()+ release_scoped_lock("whatsapp-session", record.session_path)+ messaging._whatsapp_onboarding_sessions.clear()+++def test_repair_preserves_credentials_and_starts_fresh_pairing(pairing):+ result = pairing.start(reset_session=True)++ assert result["status"] == "starting"+ assert result["qr_payload"] is None+ assert result["account_id"] is None+ assert len(pairing.starts) == 1+ assert pairing.starts[0][1] == pairing.session+ assert not (pairing.session / "creds.json").exists()+ backups = list(pairing.session.parent.glob("session-backup-*/session"))+ assert len(backups) == 1+ assert (backups[0] / "creds.json").read_text(encoding="utf-8") == pairing.creds+ assert (backups[0] / "app-state.json").read_text(encoding="utf-8") == "preserve"+ assert re.fullmatch(r"session-backup-\d{8}T\d{6}Z-.+", backups[0].parent.name)+++def test_reservation_blocks_gateway_until_cancel_before_worker_start(pairing):+ result = pairing.start(reset_session=True)+ assert pairing.gateway_can_acquire() is False+ asyncio.run(messaging.cancel_whatsapp_onboarding(result["pairing_id"]))+ assert pairing.gateway_can_acquire() is True+ assert pairing.timers[0].cancelled is True+++def test_unattended_setup_expires_and_releases_reservation(pairing):+ result = pairing.start(reset_session=True)+ assert pairing.gateway_can_acquire() is False+ pairing.timers[0].fire()+ assert messaging._whatsapp_onboarding_sessions[result["pairing_id"]].status == "expired"+ assert pairing.gateway_can_acquire() is True+++def test_failed_process_start_releases_reservation(pairing, monkeypatch):+ result = pairing.start(reset_session=True)++ def fail_spawn(*args):+ assert pairing.gateway_can_acquire() is False+ raise OSError("cannot start bridge")++ monkeypatch.setattr(messaging, "_spawn_whatsapp_pairing_process", fail_spawn)+ messaging._run_whatsapp_pairing(*pairing.starts[0])+ assert messaging._whatsapp_onboarding_sessions[result["pairing_id"]].status == "error"+ assert pairing.gateway_can_acquire() is True+++def test_recycled_pid_does_not_block_repair(pairing):+ from gateway.status import get_process_start_time++ started = get_process_start_time(os.getpid())+ assert started is not None+ (pairing.session / "bridge.pid").write_text(f"{os.getpid()}\n{started - 1}\n19877", encoding="utf-8")+ assert pairing.start(reset_session=True)["status"] == "starting"+++def test_matching_pid_fingerprint_refuses_repair(pairing):+ from gateway.status import get_process_start_time++ (pairing.session / "bridge.pid").write_text(f"{os.getpid()}\n{get_process_start_time(os.getpid())}", encoding="utf-8")+ with pytest.raises(HTTPException) as refused:+ pairing.start(reset_session=True)+ assert refused.value.status_code == 409+ assert (pairing.session / "creds.json").exists()+++class _Bridge:+ def __init__(self, lines=()):+ self.stdout = lines+ self.returncode: int | None = None++ def poll(self):+ return self.returncode++ def wait(self, timeout=None):+ self.returncode = 0 if self.returncode is None else self.returncode+ return self.returncode++ def terminate(self):+ self.returncode = -15++ def kill(self):+ self.returncode = -9+++def test_reservation_covers_connected_event_and_credential_flush(pairing, monkeypatch):+ result = pairing.start(reset_session=True)+ record = messaging._whatsapp_onboarding_sessions[result["pairing_id"]]++ def events():+ yield '{"event":"connected","user":{"id":"15550001111"}}'+ assert record.status == "connected"+ assert pairing.gateway_can_acquire() is False+ # A status poll must not release the lock before the process exits.+ asyncio.run(messaging.get_whatsapp_onboarding_status(result["pairing_id"]))+ assert pairing.gateway_can_acquire() is False++ proc = _Bridge(events())+ monkeypatch.setattr(messaging, "_spawn_whatsapp_pairing_process", lambda *args: proc)+ messaging._run_whatsapp_pairing(*pairing.starts[0])+ assert record.status == "connected"+ assert record.session_reserved is False+ assert pairing.gateway_can_acquire() is True+ assert pairing.timers[0].cancelled+++def test_expiry_stops_active_writer_and_releases_reservation(pairing, monkeypatch):+ result = pairing.start(reset_session=True)+ proc = _Bridge()++ def events():+ yield '{"event":"qr","qr":"test"}'+ assert pairing.gateway_can_acquire() is False+ pairing.timers[0].fire()+ assert proc.poll() is not None+ yield '{"event":"connected"}' # Late events cannot undo expiry.++ proc.stdout = events()+ monkeypatch.setattr(messaging, "_spawn_whatsapp_pairing_process", lambda *args: proc)+ messaging._run_whatsapp_pairing(*pairing.starts[0])+ assert messaging._whatsapp_onboarding_sessions[result["pairing_id"]].status == "expired"+ assert pairing.gateway_can_acquire() is True+++def test_expiry_during_spawn_keeps_reservation_until_late_process_stops(pairing, monkeypatch):+ result = pairing.start(reset_session=True)+ proc = _Bridge()++ def spawn(*args):+ pairing.timers[0].fire()+ assert pairing.gateway_can_acquire() is False+ return proc++ monkeypatch.setattr(messaging, "_spawn_whatsapp_pairing_process", spawn)+ messaging._run_whatsapp_pairing(*pairing.starts[0])+ assert proc.poll() is not None+ assert messaging._whatsapp_onboarding_sessions[result["pairing_id"]].status == "expired"+ assert pairing.gateway_can_acquire() is True+++def test_thread_start_failure_releases_reservation(pairing, monkeypatch):+ def fail_thread(*args, **kwargs):+ raise RuntimeError("cannot start thread")++ monkeypatch.setattr(messaging.threading, "Thread", fail_thread)+ with pytest.raises(RuntimeError, match="cannot start thread"):+ pairing.start(reset_session=True)+ assert pairing.gateway_can_acquire() is True+ assert pairing.timers[0].cancelled+++def test_apply_waits_for_flush_before_restarting_gateway(pairing, monkeypatch):+ from hermes_cli import config++ result = pairing.start(reset_session=True)+ record = messaging._whatsapp_onboarding_sessions[result["pairing_id"]]+ record.status = "connected"+ proc = _Bridge()+ record.proc = cast(Popen, proc)+ monkeypatch.setattr(messaging.threading, "Thread", pairing.real_thread)+ monkeypatch.setattr(config, "save_env_value", lambda *args: None)+ monkeypatch.setattr(web_server_messaging, "_write_platform_enabled", lambda *args: None)++ def wait(timeout=None):+ assert pairing.gateway_can_acquire() is False+ proc.returncode = 0+ return 0++ def restart(profile=None):+ assert proc.poll() == 0+ assert pairing.gateway_can_acquire() is True+ return {"restart_started": True}++ monkeypatch.setattr(proc, "wait", wait)+ monkeypatch.setattr(web_server_messaging, "_restart_gateway_after_whatsapp_onboarding", restart)+ assert asyncio.run(messaging.apply_whatsapp_onboarding(result["pairing_id"], web_models.WhatsAppOnboardingApply()))["ok"]+++def test_unverifiable_live_pid_stays_blocked(pairing, monkeypatch):+ from gateway import status++ (pairing.session / "bridge.pid").write_text(f"{os.getpid()}\n123", encoding="utf-8")+ monkeypatch.setattr(status, "get_process_start_time", lambda pid: None)+ with pytest.raises(HTTPException) as refused:+ pairing.start(reset_session=True)+ assert refused.value.status_code == 409+ assert pairing.gateway_can_acquire() is True+++def test_regular_start_keeps_existing_link(pairing):+ assert pairing.start()["status"] == "connected"+ assert pairing.starts == []+ assert (pairing.session / "creds.json").read_text(encoding="utf-8") == pairing.creds+ assert list(pairing.session.parent.glob("session-backup-*")) == []+++def test_repair_refuses_live_bridge_without_moving_credentials(pairing):+ (pairing.session / "bridge.pid").write_text(str(os.getpid()), encoding="utf-8")+ with pytest.raises(HTTPException) as refused:+ pairing.start(reset_session=True)+ assert refused.value.status_code == 409+ assert "bridge" in refused.value.detail.lower()+ assert (pairing.session / "creds.json").read_text(encoding="utf-8") == pairing.creds+ assert pairing.starts == []+++def test_repair_refuses_pending_pairing(pairing):+ record = web_server_messaging._WhatsAppOnboardingSession(+ proc=None, mode="bot", allowed_users="", session_path=str(pairing.session),+ expires_at="2099-01-01T00:00:00Z", expires_at_ts=time.time() + 600,+ status="installing",+ )+ messaging._whatsapp_onboarding_sessions["pending"] = record+ with pytest.raises(HTTPException) as refused:+ pairing.start(reset_session=True)+ assert refused.value.status_code == 409+ assert record.status == "installing"+ assert (pairing.session / "creds.json").exists()+++def test_repair_refuses_session_lock_owned_by_live_gateway(pairing):+ from gateway import status++ lock = status._get_scope_lock_path("whatsapp-session", str(pairing.session))+ lock.parent.mkdir(parents=True)+ # A second process is not needed to establish a refusal. Self-owned locks+ # must also remain intact instead of being borrowed and released by reset.+ record = status._build_pid_record()+ record["identity_hash"] = status._scope_hash(str(pairing.session))+ lock.write_text(json.dumps(record), encoding="utf-8")+ with pytest.raises(HTTPException) as refused:+ pairing.start(reset_session=True)+ assert refused.value.status_code == 409+ assert lock.exists()+ assert (pairing.session / "creds.json").exists()+++def test_failed_backup_aborts_before_pairing(pairing, monkeypatch):+ rename = Path.rename++ def refuse(path, target):+ if path == pairing.session:+ raise PermissionError("session is locked")+ return rename(path, target)++ monkeypatch.setattr(Path, "rename", refuse)+ with pytest.raises(HTTPException) as refused:+ pairing.start(reset_session=True)+ assert refused.value.status_code == 500+ assert (pairing.session / "creds.json").read_text(encoding="utf-8") == pairing.creds+ assert pairing.starts == []++[email protected]("windows")+def test_open_credentials_refuse_backup_on_windows(pairing):+ with (pairing.session / "creds.json").open("rb"):+ with pytest.raises(HTTPException) as refused:+ pairing.start(reset_session=True)+ assert refused.value.status_code == 500+ assert (pairing.session / "creds.json").read_text(encoding="utf-8") == pairing.creds+ assert pairing.starts == []+++def test_apply_retains_flushing_bridge_for_reset_guard(pairing, monkeypatch):+ from hermes_cli import config++ result = pairing.start()+ record = messaging._whatsapp_onboarding_sessions[result["pairing_id"]]+ record.proc = cast(Popen, SimpleNamespace(poll=lambda: None))+ monkeypatch.setattr(config, "save_env_value", lambda *args: None)+ monkeypatch.setattr(web_server_messaging, "_write_platform_enabled", lambda *args: None)+ monkeypatch.setattr(web_server_messaging, "_restart_gateway_after_whatsapp_onboarding", lambda profile=None: {"restart_started": True})+ asyncio.run(messaging.apply_whatsapp_onboarding(result["pairing_id"], web_models.WhatsAppOnboardingApply()))+ assert messaging._whatsapp_onboarding_sessions[result["pairing_id"]] is record+ with pytest.raises(HTTPException) as refused:+ pairing.start(reset_session=True)+ assert refused.value.status_code == 409+ assert (pairing.session / "creds.json").read_text(encoding="utf-8") == pairing.creds+++def test_cancel_during_process_start_cannot_race_session_backup(pairing, monkeypatch):+ result = pairing.start(reset_session=True)+ record = messaging._whatsapp_onboarding_sessions[result["pairing_id"]]++ def spawn(session_path, mode):+ asyncio.run(messaging.cancel_whatsapp_onboarding(result["pairing_id"]))+ with pytest.raises(HTTPException) as refused:+ pairing.start(reset_session=True)+ assert refused.value.status_code == 409+ raise OSError("pairing cancelled during process startup")++ monkeypatch.setattr(messaging, "_spawn_whatsapp_pairing_process", spawn)+ messaging._run_whatsapp_pairing(*pairing.starts[0])+ assert record.status == "cancelled"+ assert record.starting_process is False+ assert pairing.start(reset_session=True)["status"] == "starting"+++def test_repair_selected_profile_leaves_default_session_untouched(pairing, monkeypatch):+ from hermes_cli import web_server_profiles++ other = pairing.home / "profiles" / "work"+ other.mkdir(parents=True)+ (other / "config.yaml").write_text("model: test\n", encoding="utf-8")+ session = other / "platforms" / "whatsapp" / "session"+ session.mkdir(parents=True)+ (session / "creds.json").write_text('{"registered":true}', encoding="utf-8")+ monkeypatch.setattr(web_server_profiles, "_resolve_profile_dir", lambda profile: other)++ result = pairing.start(profile="work", reset_session=True)+ assert result["status"] == "starting"+ assert pairing.starts[0][1] == session+ assert not (session / "creds.json").exists()+ assert (pairing.session / "creds.json").read_text(encoding="utf-8") == pairing.creds+ observed = []++ def spawn(*args):+ from hermes_constants import get_hermes_home++ observed.append(get_hermes_home())+ raise OSError("stop after checking the worker profile")++ monkeypatch.setattr(messaging, "_spawn_whatsapp_pairing_process", spawn)+ pairing.workers[0].target(*pairing.starts[0])+ assert observed == [other]+++def test_query_profile_is_honored_for_repair(pairing, monkeypatch):+ from fastapi import FastAPI+ import httpx++ from hermes_cli import web_server_profiles++ other = pairing.home / "profiles" / "work"+ other.mkdir(parents=True)+ (other / "config.yaml").write_text("model: test\n", encoding="utf-8")+ session = other / "platforms" / "whatsapp" / "session"+ session.mkdir(parents=True)+ (session / "creds.json").write_text('{"registered":true}', encoding="utf-8")+ monkeypatch.setattr(web_server_profiles, "_resolve_profile_dir", lambda profile: other)+ app = FastAPI()+ app.include_router(messaging.router)++ async def request():+ async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://test") as client:+ return await client.post("/api/messaging/whatsapp/onboarding/start?profile=work", json={"reset_session": True})++ response = asyncio.run(request())+ assert response.status_code == 200+ assert response.json()["status"] == "starting"+ assert pairing.starts[0][1] == session+ assert (pairing.session / "creds.json").exists()diff --git a/web/src/lib/api-whatsapp.ts b/web/src/lib/api-whatsapp.tsnew file mode 100644index 00000000000..78c539ed227--- /dev/null+++ b/web/src/lib/api-whatsapp.ts@@ -0,0 +1,37 @@+export interface WhatsAppOnboardingStartRequest {+ mode?: "bot" | "self-chat";+ allowed_users?: string;+ reset_session?: boolean;+}++export interface WhatsAppOnboardingStartResponse {+ pairing_id: string;+ status:+ | "starting"+ | "installing"+ | "waiting"+ | "connected"+ | "error"+ | "expired"+ | "cancelled";+ qr_payload?: string | null;+ expires_at: string;+ mode: "bot" | "self-chat";+ allowed_users: string;+ account_id?: string | null;+ account_name?: string | null;+ account_phone?: string | null;+ error?: string | null;+}++export type WhatsAppOnboardingStatusResponse = WhatsAppOnboardingStartResponse;++export interface WhatsAppOnboardingApplyResponse {+ ok: boolean;+ platform: "whatsapp";+ needs_restart: boolean;+ restart_started?: boolean;+ restart_action?: string;+ restart_pid?: number | null;+ restart_error?: string;+}diff --git a/web/src/lib/api.test.ts b/web/src/lib/api.test.tsindex 7020a993257..b829995af90 100644--- a/web/src/lib/api.test.ts+++ b/web/src/lib/api.test.ts@@ -114,6 +114,18 @@ describe("api.getModelOptions", () => {});describe("management profile scope", () => {+ it("sends explicit WhatsApp re-pair consent to the selected profile", async () => {+ const fetchMock = jsonFetchMock({ pairing_id: "fresh", status: "starting" });+ vi.stubGlobal("fetch", fetchMock);+ setManagementProfile("worker");++ await api.startWhatsAppOnboarding({ mode: "bot", reset_session: true });++ const [url, init] = fetchMock.mock.calls[0];+ expect(url).toBe("/api/messaging/whatsapp/onboarding/start?profile=worker");+ expect(JSON.parse(String(init?.body))).toEqual({ mode: "bot", reset_session: true });+ });+// Every family whose routes write into a named profile's home must carry the// scope; an unprofiled request 400s on a host that merely HAS a second profile.it.each([diff --git a/web/src/lib/api.ts b/web/src/lib/api.tsindex 397e631864c..d3dbe2cd045 100644--- a/web/src/lib/api.ts+++ b/web/src/lib/api.ts@@ -9,6 +9,17 @@ const mutateSessionHttp = createDashboardSessionMutations(fetchJSON);import type { AuxiliaryModelsResponse } from "./api-aux";import type { AgentPluginUpdateResponse } from "./api-plugins";+import type {+ WhatsAppOnboardingApplyResponse,+ WhatsAppOnboardingStartRequest,+ WhatsAppOnboardingStartResponse,+ WhatsAppOnboardingStatusResponse,+} from "./api-whatsapp";+export type {+ WhatsAppOnboardingApplyResponse,+ WhatsAppOnboardingStartResponse,+ WhatsAppOnboardingStatusResponse,+} from "./api-whatsapp";import type {ManagedFileReadResponse,ManagedFilesResponse,@@ -1004,10 +1015,7 @@ export const api = {`/api/messaging/telegram/onboarding/${encodeURIComponent(pairingId)}`,{ method: "DELETE" },),- startWhatsAppOnboarding: (body: {- mode?: "bot" | "self-chat";- allowed_users?: string;- }) =>+ startWhatsAppOnboarding: (body: WhatsAppOnboardingStartRequest) =>fetchJSON<WhatsAppOnboardingStartResponse>("/api/messaging/whatsapp/onboarding/start",{@@ -2184,38 +2192,6 @@ export interface TelegramOnboardingApplyResponse {restart_error?: string;}-export interface WhatsAppOnboardingStartResponse {- pairing_id: string;- status:- | "starting"- | "installing"- | "waiting"- | "connected"- | "error"- | "expired"- | "cancelled";- qr_payload?: string | null;- expires_at: string;- mode: "bot" | "self-chat";- allowed_users: string;- account_id?: string | null;- account_name?: string | null;- account_phone?: string | null;- error?: string | null;-}--export type WhatsAppOnboardingStatusResponse = WhatsAppOnboardingStartResponse;--export interface WhatsAppOnboardingApplyResponse {- ok: boolean;- platform: "whatsapp";- needs_restart: boolean;- restart_started?: boolean;- restart_action?: string;- restart_pid?: number | null;- restart_error?: string;-}-export interface SessionMessage {role: "user" | "assistant" | "system" | "tool";content: string | null;diff --git a/web/src/pages/ChannelsPage.tsx b/web/src/pages/ChannelsPage.tsxindex ffc4da96f64..02a23fd3679 100644--- a/web/src/pages/ChannelsPage.tsx+++ b/web/src/pages/ChannelsPage.tsx@@ -35,6 +35,7 @@ import type {} from "@/lib/api";import { useModalBehavior } from "@/hooks/useModalBehavior";import { AllowlistInput } from "@/components/AllowlistInput";+import { ConfirmDialog } from "@/components/ConfirmDialog";import { usePageHeader } from "@/contexts/usePageHeader";import { cn, themedBody } from "@/lib/utils";import { errorMessage } from "@/lib/api-error";@@ -684,7 +685,7 @@ export default function ChannelsPage() {);}-function WhatsAppOnboardingPanel({+export function WhatsAppOnboardingPanel({onChanged,onRestartNeeded,platform,@@ -712,6 +713,7 @@ function WhatsAppOnboardingPanel({configuredMode ?? "bot",);const [allowedUsers, setAllowedUsers] = useState("");+ const [confirmRepair, setConfirmRepair] = useState(false);const [error, setError] = useState("");const [tick, setTick] = useState(0);@@ -796,7 +798,9 @@ function WhatsAppOnboardingPanel({setError("");};- const start = async () => {+ const start = async (resetSession = false) => {+ setConfirmRepair(false);+ setSetup(null);setPhase("starting");setError("");setQrDataUrl("");@@ -804,6 +808,7 @@ function WhatsAppOnboardingPanel({const res = await api.startWhatsAppOnboarding({mode,allowed_users: allowedUsers,+ reset_session: resetSession,});setSetup(res);if (res.qr_payload) {@@ -923,6 +928,7 @@ function WhatsAppOnboardingPanel({: !allowedUsers.trim() && hasSavedAllowedUsers? "Hermes will keep the saved WhatsApp allowlist.": "If no allowed numbers were entered, Hermes replies with a pairing code. Approve it from the dashboard Pairing page.";+ const pairingBusy = ["starting", "waiting", "applying"].includes(phase);return (<div className="rounded-sm border border-border bg-background/35 p-4">@@ -932,11 +938,19 @@ function WhatsAppOnboardingPanel({size="sm"className="uppercase"onClick={() => void start()}- disabled={phase === "starting" || phase === "waiting" || phase === "applying"}+ disabled={pairingBusy}prefix={phase === "starting" ? <Spinner /> : <QrCode className="h-4 w-4" />}>{phase === "starting" ? "Starting…" : "Pair with QR"}</Button>+ <Button+ size="sm"+ outlined+ onClick={() => setConfirmRepair(true)}+ disabled={pairingBusy}+ >+ Re-pair with QR+ </Button>{platform.configured && (<span className="text-xs text-muted-foreground">Existing WhatsApp settings are configured.@@ -944,6 +958,16 @@ function WhatsAppOnboardingPanel({)}</div>+ <ConfirmDialog+ open={confirmRepair}+ title="Replace the saved WhatsApp link?"+ description="Use this if WhatsApp logged out or removed this linked device. Disable WhatsApp and restart the gateway first. The old session will be kept in a private backup. Scan the new QR from Linked Devices on your phone, then Save and restart to enable WhatsApp again."+ confirmLabel="Back up and re-pair"+ destructive+ onCancel={() => setConfirmRepair(false)}+ onConfirm={() => void start(true)}+ />+<div className="flex flex-col gap-3 lg:flex-row lg:items-end"><div className="grid gap-1.5"><span className="text-xs uppercase tracking-[0.12em] text-muted-foreground">diff --git a/web/src/pages/ChannelsPage.whatsapp.test.tsx b/web/src/pages/ChannelsPage.whatsapp.test.tsxnew file mode 100644index 00000000000..3cc4e37e496--- /dev/null+++ b/web/src/pages/ChannelsPage.whatsapp.test.tsx@@ -0,0 +1,84 @@+// @vitest-environment jsdom+import { act } from "react";+import { createRoot, type Root } from "react-dom/client";+import { afterEach, beforeEach, expect, it, vi } from "vitest";++import type { MessagingPlatform } from "@/lib/api";+import { WhatsAppOnboardingPanel } from "./ChannelsPage";++const start = vi.hoisted(() => vi.fn());+vi.mock("@/lib/api", () => ({ api: { startWhatsAppOnboarding: start } }));++let root: Root;+let container: HTMLDivElement;+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;++const platform = {+ id: "whatsapp",+ configured: true,+ whatsapp_setup: { mode: "bot", allowed_users_set: true },+} as MessagingPlatform;++function button(label: string) {+ const found = Array.from(document.querySelectorAll("button")).find(+ (element) => element.textContent?.trim() === label,+ );+ if (!found) throw new Error(`Missing button: ${label}`);+ return found;+}++async function click(label: string) {+ await act(async () => { button(label).click(); });+}++beforeEach(async () => {+ start.mockReset();+ start.mockResolvedValue({+ pairing_id: "fresh", status: "starting", mode: "bot", allowed_users: "",+ expires_at: new Date(Date.now() + 600_000).toISOString(),+ });+ container = document.createElement("div");+ document.body.append(container);+ root = createRoot(container);+ await act(async () => {+ root.render(+ <WhatsAppOnboardingPanel+ platform={platform}+ onChanged={vi.fn(async () => undefined)}+ onRestartNeeded={vi.fn()}+ setRestartNeeded={vi.fn()}+ showToast={vi.fn()}+ />,+ );+ });+});++afterEach(async () => {+ await act(async () => { root.unmount(); });+ container.remove();+});++it("requires explicit confirmation before replacing the saved link", async () => {+ await click("Re-pair with QR");+ expect(start).not.toHaveBeenCalled();+ expect(document.querySelector('[role="dialog"]')?.textContent).toContain("private backup");+ await click("Cancel");+ expect(start).not.toHaveBeenCalled();+ await click("Re-pair with QR");+ await click("Back up and re-pair");+ expect(start).toHaveBeenCalledWith({ mode: "bot", allowed_users: "", reset_session: true });+ expect(button("Re-pair with QR").disabled).toBe(true);+});++it("keeps ordinary pairing non-destructive", async () => {+ await click("Pair with QR");+ expect(start).toHaveBeenCalledWith({ mode: "bot", allowed_users: "", reset_session: false });+});++it("shows an active-bridge refusal and allows retry", async () => {+ start.mockRejectedValueOnce(new Error("The WhatsApp bridge is still running. Stop it before re-pairing."));+ await click("Re-pair with QR");+ await click("Back up and re-pair");+ expect(container.textContent).toContain("Stop it before re-pairing");+ expect(button("Re-pair with QR").disabled).toBe(false);+});