From 775d3655128e98aaefeba3785ba2cf3dd857dd4a Mon Sep 17 00:00:00 2001
From: Nicole Rappe <nicole.rappe@bunny-lab.io>
Date: Sat, 18 Oct 2025 02:52:15 -0600
Subject: [PATCH 01/14] Handle missing devices and relax agent auth retries

---
 Data/Agent/agent.py                     |  76 +++++++++++++-----
 Data/Server/Modules/auth/device_auth.py | 102 ++++++++++++++++++++++++
 Data/Server/Modules/tokens/routes.py    |  15 +++-
 3 files changed, 173 insertions(+), 20 deletions(-)

diff --git a/Data/Agent/agent.py b/Data/Agent/agent.py
index 4bd933f..b54c5f8 100644
--- a/Data/Agent/agent.py
+++ b/Data/Agent/agent.py
@@ -23,7 +23,7 @@ import ssl
 import threading
 import contextlib
 import errno
-from typing import Any, Dict, Optional, List, Callable
+from typing import Any, Dict, Optional, List, Callable, Tuple
 
 import requests
 try:
@@ -1007,10 +1007,22 @@ class AgentHttpClient:
             timeout=20,
         )
         if resp.status_code in (401, 403):
-            _log_agent("Refresh token rejected; re-enrolling", fname="agent.error.log")
-            self._clear_tokens_locked()
-            self._perform_enrollment_locked()
-            return
+            error_code, snippet = self._error_details(resp)
+            if resp.status_code == 401 and self._should_retry_auth(resp.status_code, error_code):
+                _log_agent(
+                    "Refresh token rejected; attempting re-enrollment"
+                    f" error={error_code or '<unknown>'}",
+                    fname="agent.error.log",
+                )
+                self._clear_tokens_locked()
+                self._perform_enrollment_locked()
+                return
+            _log_agent(
+                "Refresh token request forbidden "
+                f"status={resp.status_code} error={error_code or '<unknown>'}"
+                f" body_snippet={snippet}",
+                fname="agent.error.log",
+            )
         resp.raise_for_status()
         data = resp.json()
         access_token = data.get("access_token")
@@ -1036,6 +1048,33 @@ class AgentHttpClient:
         self.guid = self.key_store.load_guid()
         self.session.headers.pop("Authorization", None)
 
+    def _error_details(self, response: requests.Response) -> Tuple[Optional[str], str]:
+        error_code: Optional[str] = None
+        snippet = ""
+        try:
+            snippet = response.text[:256]
+        except Exception:
+            snippet = "<unavailable>"
+        try:
+            data = response.json()
+        except Exception:
+            data = None
+        if isinstance(data, dict):
+            for key in ("error", "code", "status"):
+                value = data.get(key)
+                if isinstance(value, str) and value.strip():
+                    error_code = value.strip()
+                    break
+        return error_code, snippet
+
+    def _should_retry_auth(self, status_code: int, error_code: Optional[str]) -> bool:
+        if status_code == 401:
+            return True
+        retryable_forbidden = {"fingerprint_mismatch"}
+        if status_code == 403 and error_code in retryable_forbidden:
+            return True
+        return False
+
     def _resolve_installer_code(self) -> str:
         if INSTALLER_CODE_OVERRIDE:
             return INSTALLER_CODE_OVERRIDE
@@ -1068,20 +1107,19 @@ class AgentHttpClient:
         headers = self.auth_headers()
         response = self.session.post(url, json=payload, headers=headers, timeout=30)
         if response.status_code in (401, 403) and require_auth:
-            snippet = ""
-            try:
-                snippet = response.text[:256]
-            except Exception:
-                snippet = "<unavailable>"
-            _log_agent(
-                "Authenticated request rejected "
-                f"path={path} status={response.status_code} body_snippet={snippet}",
-                fname="agent.error.log",
-            )
-            self.clear_tokens()
-            self.ensure_authenticated()
-            headers = self.auth_headers()
-            response = self.session.post(url, json=payload, headers=headers, timeout=30)
+            error_code, snippet = self._error_details(response)
+            if self._should_retry_auth(response.status_code, error_code):
+                self.clear_tokens()
+                self.ensure_authenticated()
+                headers = self.auth_headers()
+                response = self.session.post(url, json=payload, headers=headers, timeout=30)
+            else:
+                _log_agent(
+                    "Authenticated request rejected "
+                    f"path={path} status={response.status_code} error={error_code or '<unknown>'}"
+                    f" body_snippet={snippet}",
+                    fname="agent.error.log",
+                )
         response.raise_for_status()
         if response.headers.get("Content-Type", "").lower().startswith("application/json"):
             return response.json()
diff --git a/Data/Server/Modules/auth/device_auth.py b/Data/Server/Modules/auth/device_auth.py
index 4d1c716..177d4b5 100644
--- a/Data/Server/Modules/auth/device_auth.py
+++ b/Data/Server/Modules/auth/device_auth.py
@@ -1,7 +1,10 @@
 from __future__ import annotations
 
 import functools
+import sqlite3
+import time
 from dataclasses import dataclass
+from datetime import datetime, timezone
 from typing import Any, Callable, Dict, Optional
 
 import jwt
@@ -98,6 +101,9 @@ class DeviceAuthManager:
                 (guid,),
             )
             row = cur.fetchone()
+
+            if not row:
+                row = self._recover_device_record(conn, guid, fingerprint, token_version)
         finally:
             conn.close()
 
@@ -147,6 +153,102 @@ class DeviceAuthManager:
         )
         return ctx
 
+    def _recover_device_record(
+        self,
+        conn: sqlite3.Connection,
+        guid: str,
+        fingerprint: str,
+        token_version: int,
+    ) -> Optional[tuple]:
+        """Attempt to recreate a missing device row for an authenticated token."""
+
+        guid = (guid or "").strip()
+        fingerprint = (fingerprint or "").strip()
+        if not guid or not fingerprint:
+            return None
+
+        cur = conn.cursor()
+        now_ts = int(time.time())
+        try:
+            now_iso = datetime.now(tz=timezone.utc).isoformat()
+        except Exception:
+            now_iso = datetime.utcnow().isoformat()  # pragma: no cover
+
+        base_hostname = f"RECOVERED-{guid[:12].upper()}" if guid else "RECOVERED"
+
+        for attempt in range(6):
+            hostname = base_hostname if attempt == 0 else f"{base_hostname}-{attempt}"
+            try:
+                cur.execute(
+                    """
+                    INSERT INTO devices (
+                        guid,
+                        hostname,
+                        created_at,
+                        last_seen,
+                        ssl_key_fingerprint,
+                        token_version,
+                        status,
+                        key_added_at
+                    )
+                    VALUES (?, ?, ?, ?, ?, ?, 'active', ?)
+                    """,
+                    (
+                        guid,
+                        hostname,
+                        now_ts,
+                        now_ts,
+                        fingerprint,
+                        max(token_version or 1, 1),
+                        now_iso,
+                    ),
+                )
+            except sqlite3.IntegrityError as exc:
+                # Hostname collision – try again with a suffixed placeholder.
+                message = str(exc).lower()
+                if "hostname" in message and "unique" in message:
+                    continue
+                self._log(
+                    "server",
+                    f"device auth failed to recover guid={guid} due to integrity error: {exc}",
+                )
+                conn.rollback()
+                return None
+            except Exception as exc:  # pragma: no cover - defensive logging
+                self._log(
+                    "server",
+                    f"device auth unexpected error recovering guid={guid}: {exc}",
+                )
+                conn.rollback()
+                return None
+            else:
+                conn.commit()
+                break
+        else:
+            # Exhausted attempts because of hostname collisions.
+            self._log(
+                "server",
+                f"device auth could not recover guid={guid}; hostname collisions persisted",
+            )
+            conn.rollback()
+            return None
+
+        cur.execute(
+            """
+            SELECT guid, ssl_key_fingerprint, token_version, status
+              FROM devices
+             WHERE guid = ?
+            """,
+            (guid,),
+        )
+        row = cur.fetchone()
+        if not row:
+            self._log(
+                "server",
+                f"device auth recovery for guid={guid} committed but row still missing",
+            )
+        return row
+
 
 def require_device_auth(manager: DeviceAuthManager):
     def decorator(func):
diff --git a/Data/Server/Modules/tokens/routes.py b/Data/Server/Modules/tokens/routes.py
index 1e69d9d..8005836 100644
--- a/Data/Server/Modules/tokens/routes.py
+++ b/Data/Server/Modules/tokens/routes.py
@@ -93,7 +93,20 @@ def register(
                 except DPoPVerificationError:
                     return jsonify({"error": "dpop_invalid"}), 400
             elif stored_jkt:
-                return jsonify({"error": "dpop_required"}), 400
+                # The agent does not yet emit DPoP proofs; allow recovery by clearing
+                # the stored binding so refreshes can succeed.  This preserves
+                # backward compatibility while the client gains full DPoP support.
+                try:
+                    app.logger.warning(
+                        "Clearing stored DPoP binding for guid=%s due to missing proof",
+                        guid,
+                    )
+                except Exception:
+                    pass
+                cur.execute(
+                    "UPDATE refresh_tokens SET dpop_jkt = NULL WHERE id = ?",
+                    (record_id,),
+                )
 
             new_access_token = jwt_service.issue_access_token(
                 guid,

From 8177cc0892ef3946c2c46c6e7b11e9600f01877f Mon Sep 17 00:00:00 2001
From: Nicole Rappe <nicole.rappe@bunny-lab.io>
Date: Sat, 18 Oct 2025 03:19:26 -0600
Subject: [PATCH 02/14] Support multi-use installer codes and reuse

---
 Data/Server/Modules/admin/routes.py           |  52 ++++-
 Data/Server/Modules/db_migrations.py          |  28 ++-
 Data/Server/Modules/enrollment/routes.py      | 115 ++++++++--
 Data/Server/Modules/jobs/prune.py             |   7 +-
 .../WebUI/src/Admin/Enrollment_Codes.jsx      |  37 ++-
 tests/test_enrollment_install_codes.py        | 213 ++++++++++++++++++
 6 files changed, 416 insertions(+), 36 deletions(-)
 create mode 100644 tests/test_enrollment_install_codes.py

diff --git a/Data/Server/Modules/admin/routes.py b/Data/Server/Modules/admin/routes.py
index 97625d1..72c9d81 100644
--- a/Data/Server/Modules/admin/routes.py
+++ b/Data/Server/Modules/admin/routes.py
@@ -54,18 +54,27 @@ def register(
         try:
             cur = conn.cursor()
             sql = """
-                SELECT id, code, expires_at, created_by_user_id, used_at, used_by_guid
+                SELECT id,
+                       code,
+                       expires_at,
+                       created_by_user_id,
+                       used_at,
+                       used_by_guid,
+                       max_uses,
+                       use_count,
+                       last_used_at
                   FROM enrollment_install_codes
             """
             params: List[str] = []
+            now_iso = _iso(_now())
             if status_filter == "active":
-                sql += " WHERE used_at IS NULL AND expires_at > ?"
-                params.append(_iso(_now()))
+                sql += " WHERE use_count < max_uses AND expires_at > ?"
+                params.append(now_iso)
             elif status_filter == "expired":
-                sql += " WHERE used_at IS NULL AND expires_at <= ?"
-                params.append(_iso(_now()))
+                sql += " WHERE use_count < max_uses AND expires_at <= ?"
+                params.append(now_iso)
             elif status_filter == "used":
-                sql += " WHERE used_at IS NOT NULL"
+                sql += " WHERE use_count >= max_uses"
             sql += " ORDER BY expires_at ASC"
             cur.execute(sql, params)
             rows = cur.fetchall()
@@ -82,6 +91,9 @@ def register(
                     "created_by_user_id": row[3],
                     "used_at": row[4],
                     "used_by_guid": row[5],
+                    "max_uses": row[6],
+                    "use_count": row[7],
+                    "last_used_at": row[8],
                 }
             )
         return jsonify({"codes": records})
@@ -93,6 +105,18 @@ def register(
         if ttl_hours not in VALID_TTL_HOURS:
             return jsonify({"error": "invalid_ttl"}), 400
 
+        max_uses_value = payload.get("max_uses")
+        if max_uses_value is None:
+            max_uses_value = payload.get("allowed_uses")
+        try:
+            max_uses = int(max_uses_value)
+        except Exception:
+            max_uses = 2
+        if max_uses < 1:
+            max_uses = 1
+        if max_uses > 10:
+            max_uses = 10
+
         user = current_user() or {}
         username = user.get("username") or ""
 
@@ -106,22 +130,28 @@ def register(
             cur.execute(
                 """
                 INSERT INTO enrollment_install_codes (
-                    id, code, expires_at, created_by_user_id
+                    id, code, expires_at, created_by_user_id, max_uses, use_count
                 )
-                VALUES (?, ?, ?, ?)
+                VALUES (?, ?, ?, ?, ?, 0)
                 """,
-                (record_id, code_value, _iso(expires_at), created_by),
+                (record_id, code_value, _iso(expires_at), created_by, max_uses),
             )
             conn.commit()
         finally:
             conn.close()
 
-        log("server", f"installer code created id={record_id} by={username} ttl={ttl_hours}h")
+        log(
+            "server",
+            f"installer code created id={record_id} by={username} ttl={ttl_hours}h max_uses={max_uses}",
+        )
         return jsonify(
             {
                 "id": record_id,
                 "code": code_value,
                 "expires_at": _iso(expires_at),
+                "max_uses": max_uses,
+                "use_count": 0,
+                "last_used_at": None,
             }
         )
 
@@ -131,7 +161,7 @@ def register(
         try:
             cur = conn.cursor()
             cur.execute(
-                "DELETE FROM enrollment_install_codes WHERE id = ? AND used_at IS NULL",
+                "DELETE FROM enrollment_install_codes WHERE id = ? AND use_count = 0",
                 (code_id,),
             )
             deleted = cur.rowcount
diff --git a/Data/Server/Modules/db_migrations.py b/Data/Server/Modules/db_migrations.py
index 5edd6c9..b6d1aa1 100644
--- a/Data/Server/Modules/db_migrations.py
+++ b/Data/Server/Modules/db_migrations.py
@@ -152,7 +152,10 @@ def _ensure_install_code_table(conn: sqlite3.Connection) -> None:
             expires_at TEXT NOT NULL,
             created_by_user_id TEXT,
             used_at TEXT,
-            used_by_guid TEXT
+            used_by_guid TEXT,
+            max_uses INTEGER NOT NULL DEFAULT 1,
+            use_count INTEGER NOT NULL DEFAULT 0,
+            last_used_at TEXT
         )
         """
     )
@@ -163,6 +166,29 @@ def _ensure_install_code_table(conn: sqlite3.Connection) -> None:
         """
     )
 
+    columns = {row[1] for row in _table_info(cur, "enrollment_install_codes")}
+    if "max_uses" not in columns:
+        cur.execute(
+            """
+            ALTER TABLE enrollment_install_codes
+                ADD COLUMN max_uses INTEGER NOT NULL DEFAULT 1
+            """
+        )
+    if "use_count" not in columns:
+        cur.execute(
+            """
+            ALTER TABLE enrollment_install_codes
+                ADD COLUMN use_count INTEGER NOT NULL DEFAULT 0
+            """
+        )
+    if "last_used_at" not in columns:
+        cur.execute(
+            """
+            ALTER TABLE enrollment_install_codes
+                ADD COLUMN last_used_at TEXT
+            """
+        )
+
 
 def _ensure_device_approval_table(conn: sqlite3.Connection) -> None:
     cur = conn.cursor()
diff --git a/Data/Server/Modules/enrollment/routes.py b/Data/Server/Modules/enrollment/routes.py
index c408bcd..3392cab 100644
--- a/Data/Server/Modules/enrollment/routes.py
+++ b/Data/Server/Modules/enrollment/routes.py
@@ -6,7 +6,7 @@ import sqlite3
 import uuid
 from datetime import datetime, timezone, timedelta
 import time
-from typing import Any, Callable, Dict, Optional
+from typing import Any, Callable, Dict, Optional, Tuple
 
 from flask import Blueprint, jsonify, request
 
@@ -66,31 +66,79 @@ def register(
 
     def _load_install_code(cur: sqlite3.Cursor, code_value: str) -> Optional[Dict[str, Any]]:
         cur.execute(
-            "SELECT id, code, expires_at, used_at FROM enrollment_install_codes WHERE code = ?",
+            """
+            SELECT id,
+                   code,
+                   expires_at,
+                   used_at,
+                   used_by_guid,
+                   max_uses,
+                   use_count,
+                   last_used_at
+              FROM enrollment_install_codes
+             WHERE code = ?
+            """,
             (code_value,),
         )
         row = cur.fetchone()
         if not row:
             return None
-        keys = ["id", "code", "expires_at", "used_at"]
+        keys = [
+            "id",
+            "code",
+            "expires_at",
+            "used_at",
+            "used_by_guid",
+            "max_uses",
+            "use_count",
+            "last_used_at",
+        ]
         record = dict(zip(keys, row))
         return record
 
-    def _install_code_valid(record: Dict[str, Any]) -> bool:
+    def _install_code_valid(
+        record: Dict[str, Any], fingerprint: str, cur: sqlite3.Cursor
+    ) -> Tuple[bool, Optional[str]]:
         if not record:
-            return False
+            return False, None
         expires_at = record.get("expires_at")
         if not isinstance(expires_at, str):
-            return False
+            return False, None
         try:
             expiry = datetime.fromisoformat(expires_at)
         except Exception:
-            return False
+            return False, None
         if expiry <= _now():
-            return False
-        if record.get("used_at"):
-            return False
-        return True
+            return False, None
+        try:
+            max_uses = int(record.get("max_uses") or 1)
+        except Exception:
+            max_uses = 1
+        if max_uses < 1:
+            max_uses = 1
+        try:
+            use_count = int(record.get("use_count") or 0)
+        except Exception:
+            use_count = 0
+        if use_count < max_uses:
+            return True, None
+
+        guid = str(record.get("used_by_guid") or "").strip()
+        if not guid:
+            return False, None
+        cur.execute(
+            "SELECT ssl_key_fingerprint FROM devices WHERE guid = ?",
+            (guid,),
+        )
+        row = cur.fetchone()
+        if not row:
+            return False, None
+        stored_fp = (row[0] or "").strip().lower()
+        if not stored_fp:
+            return False, None
+        if stored_fp == (fingerprint or "").strip().lower():
+            return True, guid
+        return False, None
 
     def _normalize_host(hostname: str, guid: str, cur: sqlite3.Cursor) -> str:
         base = (hostname or "").strip() or guid
@@ -305,7 +353,13 @@ def register(
         try:
             cur = conn.cursor()
             install_code = _load_install_code(cur, enrollment_code)
-            if not _install_code_valid(install_code):
+            valid_code, reuse_guid = _install_code_valid(install_code, fingerprint, cur)
+            if not valid_code:
+                log(
+                    "server",
+                    "enrollment request invalid_code "
+                    f"host={hostname} fingerprint={fingerprint[:12]} code_mask={_mask_code(enrollment_code)}",
+                )
                 return jsonify({"error": "invalid_enrollment_code"}), 400
 
             approval_reference: str
@@ -331,6 +385,7 @@ def register(
                     """
                     UPDATE device_approvals
                        SET hostname_claimed = ?,
+                           guid = ?,
                            enrollment_code_id = ?,
                            client_nonce = ?,
                            server_nonce = ?,
@@ -340,6 +395,7 @@ def register(
                     """,
                     (
                         hostname,
+                        reuse_guid,
                         install_code["id"],
                         client_nonce_b64,
                         server_nonce_b64,
@@ -359,11 +415,12 @@ def register(
                         status, client_nonce, server_nonce, agent_pubkey_der,
                         created_at, updated_at
                     )
-                    VALUES (?, ?, NULL, ?, ?, ?, 'pending', ?, ?, ?, ?, ?)
+                    VALUES (?, ?, ?, ?, ?, ?, 'pending', ?, ?, ?, ?, ?)
                     """,
                     (
                         record_id,
                         approval_reference,
+                        reuse_guid,
                         hostname,
                         fingerprint,
                         install_code["id"],
@@ -537,14 +594,40 @@ def register(
 
             # Mark install code used
             if enrollment_code_id:
+                cur.execute(
+                    "SELECT use_count, max_uses FROM enrollment_install_codes WHERE id = ?",
+                    (enrollment_code_id,),
+                )
+                usage_row = cur.fetchone()
+                try:
+                    prior_count = int(usage_row[0]) if usage_row else 0
+                except Exception:
+                    prior_count = 0
+                try:
+                    allowed_uses = int(usage_row[1]) if usage_row else 1
+                except Exception:
+                    allowed_uses = 1
+                if allowed_uses < 1:
+                    allowed_uses = 1
+                new_count = prior_count + 1
+                consumed = new_count >= allowed_uses
                 cur.execute(
                     """
                     UPDATE enrollment_install_codes
-                       SET used_at = ?, used_by_guid = ?
+                       SET use_count = ?,
+                           used_by_guid = ?,
+                           last_used_at = ?,
+                           used_at = CASE WHEN ? THEN ? ELSE used_at END
                      WHERE id = ?
-                       AND used_at IS NULL
                     """,
-                    (now_iso, effective_guid, enrollment_code_id),
+                    (
+                        new_count,
+                        effective_guid,
+                        now_iso,
+                        1 if consumed else 0,
+                        now_iso,
+                        enrollment_code_id,
+                    ),
                 )
 
             # Update approval record with final state
diff --git a/Data/Server/Modules/jobs/prune.py b/Data/Server/Modules/jobs/prune.py
index 9c3ac56..2e6e21e 100644
--- a/Data/Server/Modules/jobs/prune.py
+++ b/Data/Server/Modules/jobs/prune.py
@@ -34,7 +34,7 @@ def _run_once(db_conn_factory: Callable[[], any], log: Callable[[str, str], None
         cur.execute(
             """
             DELETE FROM enrollment_install_codes
-             WHERE used_at IS NULL
+             WHERE use_count = 0
                AND expires_at < ?
             """,
             (now_iso,),
@@ -52,7 +52,10 @@ def _run_once(db_conn_factory: Callable[[], any], log: Callable[[str, str], None
                         SELECT 1
                           FROM enrollment_install_codes c
                          WHERE c.id = device_approvals.enrollment_code_id
-                           AND c.expires_at < ?
+                           AND (
+                               c.expires_at < ?
+                               OR c.use_count >= c.max_uses
+                           )
                      )
                     OR created_at < ?
                )
diff --git a/Data/Server/WebUI/src/Admin/Enrollment_Codes.jsx b/Data/Server/WebUI/src/Admin/Enrollment_Codes.jsx
index 236fbd7..db3e387 100644
--- a/Data/Server/WebUI/src/Admin/Enrollment_Codes.jsx
+++ b/Data/Server/WebUI/src/Admin/Enrollment_Codes.jsx
@@ -65,7 +65,9 @@ const formatDateTime = (value) => {
 
 const determineStatus = (record) => {
   if (!record) return "expired";
-  if (record.used_at) return "used";
+  const maxUses = Number.isFinite(record?.max_uses) ? record.max_uses : 1;
+  const useCount = Number.isFinite(record?.use_count) ? record.use_count : 0;
+  if (useCount >= Math.max(1, maxUses || 1)) return "used";
   if (!record.expires_at) return "expired";
   const expires = new Date(record.expires_at);
   if (Number.isNaN(expires.getTime())) return "expired";
@@ -80,6 +82,7 @@ function EnrollmentCodes() {
   const [statusFilter, setStatusFilter] = useState("all");
   const [ttlHours, setTtlHours] = useState(6);
   const [generating, setGenerating] = useState(false);
+  const [maxUses, setMaxUses] = useState(2);
 
   const filteredCodes = useMemo(() => {
     if (statusFilter === "all") return codes;
@@ -119,7 +122,7 @@ function EnrollmentCodes() {
         method: "POST",
         credentials: "include",
         headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ ttl_hours: ttlHours }),
+        body: JSON.stringify({ ttl_hours: ttlHours, max_uses: maxUses }),
       });
       if (!resp.ok) {
         const body = await resp.json().catch(() => ({}));
@@ -133,7 +136,7 @@ function EnrollmentCodes() {
     } finally {
       setGenerating(false);
     }
-  }, [fetchCodes, ttlHours]);
+  }, [fetchCodes, ttlHours, maxUses]);
 
   const handleDelete = useCallback(
     async (id) => {
@@ -216,7 +219,7 @@ function EnrollmentCodes() {
               labelId="ttl-select-label"
               label="Duration"
               value={ttlHours}
-              onChange={(event) => setTtlHours(event.target.value)}
+              onChange={(event) => setTtlHours(Number(event.target.value))}
             >
               {TTL_PRESETS.map((preset) => (
                 <MenuItem key={preset.value} value={preset.value}>
@@ -226,6 +229,22 @@ function EnrollmentCodes() {
             </Select>
           </FormControl>
 
+          <FormControl size="small" sx={{ minWidth: 160 }}>
+            <InputLabel id="uses-select-label">Allowed Uses</InputLabel>
+            <Select
+              labelId="uses-select-label"
+              label="Allowed Uses"
+              value={maxUses}
+              onChange={(event) => setMaxUses(Number(event.target.value))}
+            >
+              {[1, 2, 3, 5].map((uses) => (
+                <MenuItem key={uses} value={uses}>
+                  {uses === 1 ? "Single use" : `${uses} uses`}
+                </MenuItem>
+              ))}
+            </Select>
+          </FormControl>
+
           <Button
             variant="contained"
             color="primary"
@@ -270,7 +289,9 @@ function EnrollmentCodes() {
                 <TableCell>Installer Code</TableCell>
                 <TableCell>Expires At</TableCell>
                 <TableCell>Created By</TableCell>
-                <TableCell>Used At</TableCell>
+                <TableCell>Usage</TableCell>
+                <TableCell>Last Used</TableCell>
+                <TableCell>Consumed At</TableCell>
                 <TableCell>Used By GUID</TableCell>
                 <TableCell align="right">Actions</TableCell>
               </TableRow>
@@ -296,13 +317,17 @@ function EnrollmentCodes() {
               ) : (
                 filteredCodes.map((record) => {
                   const status = determineStatus(record);
-                  const disableDelete = status !== "active";
+                  const maxAllowed = Math.max(1, Number.isFinite(record?.max_uses) ? record.max_uses : 1);
+                  const usageCount = Math.max(0, Number.isFinite(record?.use_count) ? record.use_count : 0);
+                  const disableDelete = usageCount !== 0;
                   return (
                     <TableRow hover key={record.id}>
                       <TableCell>{renderStatusChip(record)}</TableCell>
                       <TableCell sx={{ fontFamily: "monospace" }}>{maskCode(record.code)}</TableCell>
                       <TableCell>{formatDateTime(record.expires_at)}</TableCell>
                       <TableCell>{record.created_by_user_id || "—"}</TableCell>
+                      <TableCell sx={{ fontFamily: "monospace" }}>{`${usageCount} / ${maxAllowed}`}</TableCell>
+                      <TableCell>{formatDateTime(record.last_used_at)}</TableCell>
                       <TableCell>{formatDateTime(record.used_at)}</TableCell>
                       <TableCell sx={{ fontFamily: "monospace" }}>
                         {record.used_by_guid || "—"}
diff --git a/tests/test_enrollment_install_codes.py b/tests/test_enrollment_install_codes.py
new file mode 100644
index 0000000..edcb81b
--- /dev/null
+++ b/tests/test_enrollment_install_codes.py
@@ -0,0 +1,213 @@
+import base64
+import os
+import pathlib
+import sqlite3
+import sys
+import uuid
+
+import pytest
+try:  # pragma: no cover - optional dependency
+    from cryptography.hazmat.primitives import serialization
+    from cryptography.hazmat.primitives.asymmetric import ed25519
+    _CRYPTO_IMPORT_ERROR: Exception | None = None
+except Exception as exc:  # pragma: no cover - dependency unavailable
+    serialization = None  # type: ignore
+    ed25519 = None  # type: ignore
+    _CRYPTO_IMPORT_ERROR = exc
+try:  # pragma: no cover - optional dependency
+    from flask import Flask
+    _FLASK_IMPORT_ERROR: Exception | None = None
+except Exception as exc:  # pragma: no cover - dependency unavailable
+    Flask = None  # type: ignore
+    _FLASK_IMPORT_ERROR = exc
+
+ROOT = pathlib.Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from Data.Server.Modules import db_migrations
+from Data.Server.Modules.auth.rate_limit import SlidingWindowRateLimiter
+from Data.Server.Modules.enrollment.nonce_store import NonceCache
+
+if Flask is not None:  # pragma: no cover - dependency unavailable
+    from Data.Server.Modules.enrollment import routes as enrollment_routes
+else:  # pragma: no cover - dependency unavailable
+    enrollment_routes = None  # type: ignore
+
+
+class _DummyJWTService:
+    def issue_access_token(self, guid: str, fingerprint: str, token_version: int, expires_in: int = 900, extra_claims=None):
+        return f"token-{guid}"
+
+
+class _DummySigner:
+    def public_base64_spki(self) -> str:
+        return ""
+
+
+def _make_app(db_path: str, tls_path: str):
+    if Flask is None or enrollment_routes is None:  # pragma: no cover - dependency unavailable
+        pytest.skip(f"flask unavailable: {_FLASK_IMPORT_ERROR}")
+    app = Flask(__name__)
+
+    def _factory():
+        conn = sqlite3.connect(db_path)
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    enrollment_routes.register(
+        app,
+        db_conn_factory=_factory,
+        log=lambda channel, message: None,
+        jwt_service=_DummyJWTService(),
+        tls_bundle_path=tls_path,
+        ip_rate_limiter=SlidingWindowRateLimiter(),
+        fp_rate_limiter=SlidingWindowRateLimiter(),
+        nonce_cache=NonceCache(ttl_seconds=30.0),
+        script_signer=_DummySigner(),
+    )
+    return app, _factory
+
+
+def _create_install_code(conn: sqlite3.Connection, code: str, *, max_uses: int = 2):
+    cur = conn.cursor()
+    record_id = str(uuid.uuid4())
+    cur.execute(
+        """
+        INSERT INTO enrollment_install_codes (
+            id, code, expires_at, created_by_user_id, max_uses, use_count
+        )
+        VALUES (?, ?, datetime('now', '+6 hours'), 'test-user', ?, 0)
+        """,
+        (record_id, code, max_uses),
+    )
+    conn.commit()
+    return record_id
+
+
+def _perform_enrollment_cycle(app, factory, code: str, private_key):
+    client = app.test_client()
+    public_der = private_key.public_key().public_bytes(
+        serialization.Encoding.DER,
+        serialization.PublicFormat.SubjectPublicKeyInfo,
+    )
+    public_b64 = base64.b64encode(public_der).decode("ascii")
+    client_nonce = os.urandom(32)
+    payload = {
+        "hostname": "unit-test-host",
+        "enrollment_code": code,
+        "agent_pubkey": public_b64,
+        "client_nonce": base64.b64encode(client_nonce).decode("ascii"),
+    }
+    request_resp = client.post("/api/agent/enroll/request", json=payload)
+    assert request_resp.status_code == 200
+    request_data = request_resp.get_json()
+    approval_reference = request_data["approval_reference"]
+
+    with factory() as conn:
+        cur = conn.cursor()
+        cur.execute(
+            """
+            UPDATE device_approvals
+               SET status = 'approved',
+                   approved_by_user_id = 'tester'
+             WHERE approval_reference = ?
+            """,
+            (approval_reference,),
+        )
+        cur.execute(
+            """
+            SELECT server_nonce, client_nonce
+              FROM device_approvals
+             WHERE approval_reference = ?
+            """,
+            (approval_reference,),
+        )
+        row = cur.fetchone()
+        assert row is not None
+        server_nonce_b64 = row["server_nonce"]
+
+    server_nonce = base64.b64decode(server_nonce_b64)
+    proof_message = server_nonce + approval_reference.encode("utf-8") + client_nonce
+    proof_sig = private_key.sign(proof_message)
+    poll_payload = {
+        "approval_reference": approval_reference,
+        "client_nonce": base64.b64encode(client_nonce).decode("ascii"),
+        "proof_sig": base64.b64encode(proof_sig).decode("ascii"),
+    }
+    poll_resp = client.post("/api/agent/enroll/poll", json=poll_payload)
+    assert poll_resp.status_code == 200
+    return poll_resp.get_json()
+
+
+@pytest.mark.parametrize("max_uses", [2])
+@pytest.mark.skipif(ed25519 is None, reason=f"cryptography unavailable: {_CRYPTO_IMPORT_ERROR}")
+@pytest.mark.skipif(Flask is None, reason=f"flask unavailable: {_FLASK_IMPORT_ERROR}")
+def test_install_code_allows_multiple_and_reuse(tmp_path, max_uses):
+    db_path = tmp_path / "test.db"
+    conn = sqlite3.connect(db_path)
+    db_migrations.apply_all(conn)
+    _create_install_code(conn, "TEST-CODE-1234", max_uses=max_uses)
+    conn.close()
+
+    tls_path = tmp_path / "tls.pem"
+    tls_path.write_text("TEST CERT")
+
+    app, factory = _make_app(str(db_path), str(tls_path))
+
+    private_key = ed25519.Ed25519PrivateKey.generate()
+
+    # First enrollment consumes one use but keeps the code active.
+    first = _perform_enrollment_cycle(app, factory, "TEST-CODE-1234", private_key)
+    assert first["status"] == "approved"
+
+    with factory() as conn:
+        cur = conn.cursor()
+        cur.execute(
+            "SELECT use_count, max_uses, used_at, last_used_at FROM enrollment_install_codes WHERE code = ?",
+            ("TEST-CODE-1234",),
+        )
+        row = cur.fetchone()
+        assert row is not None
+        assert row["use_count"] == 1
+        assert row["max_uses"] == max_uses
+        assert row["used_at"] is None
+        assert row["last_used_at"] is not None
+
+    # Second enrollment hits the configured max uses.
+    second = _perform_enrollment_cycle(app, factory, "TEST-CODE-1234", private_key)
+    assert second["status"] == "approved"
+
+    with factory() as conn:
+        cur = conn.cursor()
+        cur.execute(
+            "SELECT use_count, used_at, last_used_at, used_by_guid FROM enrollment_install_codes WHERE code = ?",
+            ("TEST-CODE-1234",),
+        )
+        row = cur.fetchone()
+        assert row is not None
+        assert row["use_count"] == max_uses
+        assert row["used_at"] is not None
+        assert row["last_used_at"] is not None
+        consumed_guid = row["used_by_guid"]
+        assert consumed_guid
+
+    # Additional enrollments from the same identity reuse the stored GUID even after consumption.
+    third = _perform_enrollment_cycle(app, factory, "TEST-CODE-1234", private_key)
+    assert third["status"] == "approved"
+
+    with factory() as conn:
+        cur = conn.cursor()
+        cur.execute(
+            "SELECT use_count, used_at, last_used_at, used_by_guid FROM enrollment_install_codes WHERE code = ?",
+            ("TEST-CODE-1234",),
+        )
+        row = cur.fetchone()
+        assert row is not None
+        assert row["use_count"] == max_uses + 1
+        assert row["used_by_guid"] == consumed_guid
+        assert row["used_at"] is not None
+        assert row["last_used_at"] is not None
+
+        cur.execute("SELECT COUNT(*) FROM devices WHERE guid = ?", (consumed_guid,))
+        assert cur.fetchone()[0] == 1

From 64e0c05d6697796bae8137f124c66ba64eada2d8 Mon Sep 17 00:00:00 2001
From: Nicole Rappe <nicole.rappe@bunny-lab.io>
Date: Sat, 18 Oct 2025 03:41:29 -0600
Subject: [PATCH 03/14] Share installer codes across agent contexts

---
 Data/Agent/agent.py                | 103 +++++++++++++++++++++++++++-
 Data/Agent/security.py             | 105 +++++++++++++++++++++++++++++
 tests/test_agent_installer_code.py |  58 ++++++++++++++++
 3 files changed, 263 insertions(+), 3 deletions(-)
 create mode 100644 tests/test_agent_installer_code.py

diff --git a/Data/Agent/agent.py b/Data/Agent/agent.py
index b54c5f8..ab73c6d 100644
--- a/Data/Agent/agent.py
+++ b/Data/Agent/agent.py
@@ -81,6 +81,7 @@ def _bootstrap_log(msg: str):
 # Headless/service mode flag (skip Qt and interactive UI)
 SYSTEM_SERVICE_MODE = ('--system-service' in sys.argv) or (os.environ.get('BOREALIS_AGENT_MODE') == 'system')
 SERVICE_MODE = 'system' if SYSTEM_SERVICE_MODE else 'currentuser'
+SERVICE_MODE_CANONICAL = SERVICE_MODE.upper()
 _bootstrap_log(f'agent.py loaded; SYSTEM_SERVICE_MODE={SYSTEM_SERVICE_MODE}; argv={sys.argv!r}')
 def _argv_get(flag: str, default: str = None):
     try:
@@ -571,6 +572,57 @@ DEFAULT_CONFIG = {
     "installer_code": ""
 }
 
+
+def _load_installer_code_from_file(path: str) -> str:
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            data = json.load(fh)
+    except Exception:
+        return ""
+    value = data.get("installer_code") if isinstance(data, dict) else ""
+    if isinstance(value, str):
+        return value.strip()
+    return ""
+
+
+def _fallback_installer_code(current_path: str) -> str:
+    settings_dir = os.path.dirname(current_path)
+    candidates: List[str] = []
+    suffix = CONFIG_SUFFIX_CANONICAL
+    sibling_map = {
+        "SYSTEM": "agent_settings_CURRENTUSER.json",
+        "CURRENTUSER": "agent_settings_SYSTEM.json",
+    }
+    sibling_name = sibling_map.get(suffix or "")
+    if sibling_name:
+        candidates.append(os.path.join(settings_dir, sibling_name))
+    # Prefer the shared/base config next
+    candidates.append(os.path.join(settings_dir, "agent_settings.json"))
+    # Legacy location fallback
+    try:
+        project_root = _find_project_root()
+        legacy_dir = os.path.join(project_root, "Agent", "Settings")
+        if sibling_name:
+            candidates.append(os.path.join(legacy_dir, sibling_name))
+        candidates.append(os.path.join(legacy_dir, "agent_settings.json"))
+    except Exception:
+        pass
+
+    current_abspath = os.path.abspath(current_path)
+    for candidate in candidates:
+        if not candidate:
+            continue
+        try:
+            candidate_path = os.path.abspath(candidate)
+        except Exception:
+            continue
+        if candidate_path == current_abspath or not os.path.isfile(candidate_path):
+            continue
+        code = _load_installer_code_from_file(candidate_path)
+        if code:
+            return code
+    return ""
+
 class ConfigManager:
     def __init__(self, path):
         self.path = path
@@ -1077,12 +1129,50 @@ class AgentHttpClient:
 
     def _resolve_installer_code(self) -> str:
         if INSTALLER_CODE_OVERRIDE:
-            return INSTALLER_CODE_OVERRIDE
+            code = INSTALLER_CODE_OVERRIDE.strip()
+            if code:
+                try:
+                    self.key_store.cache_installer_code(code, consumer=SERVICE_MODE_CANONICAL)
+                except Exception:
+                    pass
+            return code
+        code = ""
         try:
             code = (CONFIG.data.get("installer_code") or "").strip()
-            return code
         except Exception:
-            return ""
+            code = ""
+        if code:
+            try:
+                self.key_store.cache_installer_code(code, consumer=SERVICE_MODE_CANONICAL)
+            except Exception:
+                pass
+            return code
+        try:
+            cached = self.key_store.load_cached_installer_code()
+        except Exception:
+            cached = None
+        if cached:
+            try:
+                self.key_store.cache_installer_code(cached, consumer=SERVICE_MODE_CANONICAL)
+            except Exception:
+                pass
+            return cached
+        fallback = _fallback_installer_code(CONFIG.path)
+        if fallback:
+            try:
+                CONFIG.data["installer_code"] = fallback
+                CONFIG._write()
+                _log_agent(
+                    "Adopted installer code from sibling configuration", fname="agent.log"
+                )
+            except Exception:
+                pass
+            try:
+                self.key_store.cache_installer_code(fallback, consumer=SERVICE_MODE_CANONICAL)
+            except Exception:
+                pass
+            return fallback
+        return ""
 
     def _consume_installer_code(self) -> None:
         # Avoid clearing explicit CLI/env overrides; only mutate persisted config.
@@ -1096,6 +1186,13 @@ class AgentHttpClient:
                 _log_agent("Cleared persisted installer code after successful enrollment", fname="agent.log")
         except Exception as exc:
             _log_agent(f"Failed to clear installer code after enrollment: {exc}", fname="agent.error.log")
+        try:
+            self.key_store.mark_installer_code_consumed(SERVICE_MODE_CANONICAL)
+        except Exception as exc:
+            _log_agent(
+                f"Failed to update shared installer code cache: {exc}",
+                fname="agent.error.log",
+            )
 
     # ------------------------------------------------------------------
     # HTTP helpers
diff --git a/Data/Agent/security.py b/Data/Agent/security.py
index 443a0dd..30b935d 100644
--- a/Data/Agent/security.py
+++ b/Data/Agent/security.py
@@ -230,6 +230,7 @@ class AgentKeyStore:
         self._server_certificate_path = os.path.join(self.settings_dir, "server_certificate.pem")
         self._server_signing_key_path = os.path.join(self.settings_dir, "server_signing_key.pub")
         self._identity_lock_path = os.path.join(self.settings_dir, "identity.lock")
+        self._installer_cache_path = os.path.join(self.settings_dir, "installer_code.shared.json")
 
     # ------------------------------------------------------------------
     # Identity management
@@ -455,3 +456,107 @@ class AgentKeyStore:
         if isinstance(value, str) and value.strip():
             return value.strip()
         return None
+
+    # ------------------------------------------------------------------
+    # Installer code sharing helpers
+    # ------------------------------------------------------------------
+    def _load_installer_cache(self) -> dict:
+        if not os.path.isfile(self._installer_cache_path):
+            return {}
+        try:
+            with open(self._installer_cache_path, "r", encoding="utf-8") as fh:
+                data = json.load(fh)
+            if isinstance(data, dict):
+                return data
+        except Exception:
+            pass
+        return {}
+
+    def _store_installer_cache(self, payload: dict) -> None:
+        try:
+            with open(self._installer_cache_path, "w", encoding="utf-8") as fh:
+                json.dump(payload, fh, indent=2)
+            _restrict_permissions(self._installer_cache_path)
+        except Exception:
+            pass
+
+    def cache_installer_code(self, code: str, consumer: Optional[str] = None) -> None:
+        normalized = (code or "").strip()
+        if not normalized:
+            return
+        payload = self._load_installer_cache()
+        payload["code"] = normalized
+        consumers = set()
+        existing = payload.get("consumed")
+        if isinstance(existing, list):
+            consumers = {str(item).upper() for item in existing if isinstance(item, str)}
+        if consumer:
+            consumers.add(str(consumer).upper())
+        payload["consumed"] = sorted(consumers)
+        payload["updated_at"] = int(time.time())
+        self._store_installer_cache(payload)
+
+    def load_cached_installer_code(self) -> Optional[str]:
+        payload = self._load_installer_cache()
+        code = payload.get("code")
+        if isinstance(code, str):
+            stripped = code.strip()
+            if stripped:
+                return stripped
+        return None
+
+    def mark_installer_code_consumed(self, consumer: Optional[str] = None) -> None:
+        payload = self._load_installer_cache()
+        if not payload:
+            return
+        consumers = set()
+        existing = payload.get("consumed")
+        if isinstance(existing, list):
+            consumers = {str(item).upper() for item in existing if isinstance(item, str)}
+        if consumer:
+            consumers.add(str(consumer).upper())
+        payload["consumed"] = sorted(consumers)
+        payload["updated_at"] = int(time.time())
+
+        code_present = isinstance(payload.get("code"), str) and payload["code"].strip()
+        should_clear = False
+        if not code_present:
+            should_clear = True
+        else:
+            required_consumers = {"SYSTEM", "CURRENTUSER"}
+            if required_consumers.issubset(consumers):
+                should_clear = True
+            else:
+                remaining = required_consumers - consumers
+                if not remaining:
+                    should_clear = True
+                else:
+                    exists_other = False
+                    for other in remaining:
+                        if other == "SYSTEM":
+                            cfg_name = "agent_settings_SYSTEM.json"
+                        elif other == "CURRENTUSER":
+                            cfg_name = "agent_settings_CURRENTUSER.json"
+                        else:
+                            cfg_name = None
+                        if not cfg_name:
+                            continue
+                        path = os.path.join(self.settings_dir, cfg_name)
+                        if os.path.isfile(path):
+                            exists_other = True
+                            break
+                    if not exists_other:
+                        should_clear = True
+
+        if should_clear:
+            payload.pop("code", None)
+            payload["consumed"] = []
+
+        if payload.get("code") or payload.get("consumed"):
+            self._store_installer_cache(payload)
+        else:
+            try:
+                if os.path.isfile(self._installer_cache_path):
+                    os.remove(self._installer_cache_path)
+            except Exception:
+                pass
diff --git a/tests/test_agent_installer_code.py b/tests/test_agent_installer_code.py
new file mode 100644
index 0000000..ef6732f
--- /dev/null
+++ b/tests/test_agent_installer_code.py
@@ -0,0 +1,58 @@
+import json
+import sys
+
+import pytest
+
+
+@pytest.fixture
+def agent_module(tmp_path, monkeypatch):
+    settings_dir = tmp_path / "Agent" / "Borealis" / "Settings"
+    settings_dir.mkdir(parents=True)
+    system_config = settings_dir / "agent_settings_SYSTEM.json"
+    system_config.write_text(json.dumps({
+        "config_file_watcher_interval": 2,
+        "agent_id": "",
+        "regions": {},
+        "installer_code": "",
+    }, indent=2))
+    current_config = settings_dir / "agent_settings_CURRENTUSER.json"
+    current_config.write_text(json.dumps({
+        "config_file_watcher_interval": 2,
+        "agent_id": "",
+        "regions": {},
+        "installer_code": "",
+    }, indent=2))
+
+    monkeypatch.setenv("BOREALIS_ROOT", str(tmp_path))
+    monkeypatch.setenv("BOREALIS_AGENT_MODE", "system")
+    monkeypatch.setenv("BOREALIS_AGENT_CONFIG", "")
+    monkeypatch.setitem(sys.modules, "PyQt5", None)
+    monkeypatch.setitem(sys.modules, "qasync", None)
+    monkeypatch.setattr(sys, "argv", ["agent.py", "--system-service", "--config", "SYSTEM"], raising=False)
+
+    agent = pytest.importorskip(
+        "Data.Agent.agent", reason="agent module requires optional dependencies"
+    )
+    return agent, system_config
+
+
+def test_shared_installer_code_cache_allows_system_reuse(agent_module, tmp_path):
+    agent, system_config = agent_module
+
+    client = agent.AgentHttpClient()
+    shared_code = "SHARED-CODE-1234"
+    client.key_store.cache_installer_code(shared_code, consumer="CURRENTUSER")
+
+    # System agent should discover the cached code even though its config is empty.
+    resolved = client._resolve_installer_code()
+    assert resolved == shared_code
+
+    # Config should now persist the adopted code to avoid repeated lookups.
+    data = json.loads(system_config.read_text())
+    assert data.get("installer_code") == shared_code
+
+    # After enrollment completes, the cache should be cleared for future runs.
+    client._consume_installer_code()
+    assert client.key_store.load_cached_installer_code() is None
+    data = json.loads(system_config.read_text())
+    assert data.get("installer_code") == ""

From afa429db3f429f3f241464c50e77925efef5bf1d Mon Sep 17 00:00:00 2001
From: Nicole Rappe <nicole.rappe@bunny-lab.io>
Date: Sat, 18 Oct 2025 04:04:02 -0600
Subject: [PATCH 04/14] Clarify agent and server log context labeling

---
 Data/Agent/agent.py                      | 71 ++++++++++++++++++--
 Data/Server/Modules/admin/routes.py      |  2 +-
 Data/Server/Modules/agents/routes.py     | 24 ++++++-
 Data/Server/Modules/auth/device_auth.py  | 34 ++++++++--
 Data/Server/Modules/enrollment/routes.py | 83 +++++++++++++++++-------
 Data/Server/Modules/jobs/prune.py        |  6 +-
 Data/Server/server.py                    | 51 ++++++++++++++-
 7 files changed, 227 insertions(+), 44 deletions(-)

diff --git a/Data/Agent/agent.py b/Data/Agent/agent.py
index ab73c6d..e6e1112 100644
--- a/Data/Agent/agent.py
+++ b/Data/Agent/agent.py
@@ -23,6 +23,7 @@ import ssl
 import threading
 import contextlib
 import errno
+import re
 from typing import Any, Dict, Optional, List, Callable, Tuple
 
 import requests
@@ -66,15 +67,65 @@ def _rotate_daily(path: str):
 
 
 # Early bootstrap logging (goes to agent.log)
-def _bootstrap_log(msg: str):
+_AGENT_CONTEXT_HEADER = "X-Borealis-Agent-Context"
+_AGENT_SCOPE_PATTERN = re.compile(r"\\bscope=([A-Za-z0-9_-]+)", re.IGNORECASE)
+
+
+def _canonical_scope_value(raw: Optional[str]) -> Optional[str]:
+    if not raw:
+        return None
+    value = "".join(ch for ch in str(raw) if ch.isalnum() or ch in ("_", "-"))
+    if not value:
+        return None
+    return value.upper()
+
+
+def _agent_context_default() -> Optional[str]:
+    suffix = globals().get("CONFIG_SUFFIX_CANONICAL")
+    context = _canonical_scope_value(suffix)
+    if context:
+        return context
+    service = globals().get("SERVICE_MODE_CANONICAL")
+    context = _canonical_scope_value(service)
+    if context:
+        return context
+    return None
+
+
+def _infer_agent_scope(message: str, provided_scope: Optional[str] = None) -> Optional[str]:
+    scope = _canonical_scope_value(provided_scope)
+    if scope:
+        return scope
+    match = _AGENT_SCOPE_PATTERN.search(message or "")
+    if match:
+        scope = _canonical_scope_value(match.group(1))
+        if scope:
+            return scope
+    return _agent_context_default()
+
+
+def _format_agent_log_message(message: str, fname: str, scope: Optional[str] = None) -> str:
+    context = _infer_agent_scope(message, scope)
+    if fname == "agent.error.log":
+        prefix = "[ERROR]"
+        if context:
+            prefix = f"{prefix}[CONTEXT-{context}]"
+        return f"{prefix} {message}"
+    if context:
+        return f"[CONTEXT-{context}] {message}"
+    return f"[INFO] {message}"
+
+
+def _bootstrap_log(msg: str, *, scope: Optional[str] = None):
     try:
         base = _agent_logs_root()
         os.makedirs(base, exist_ok=True)
         path = os.path.join(base, 'agent.log')
         _rotate_daily(path)
         ts = datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S')
+        line = _format_agent_log_message(msg, 'agent.log', scope)
         with open(path, 'a', encoding='utf-8') as fh:
-            fh.write(f'[{ts}] {msg}\n')
+            fh.write(f'[{ts}] {line}\n')
     except Exception:
         pass
 
@@ -360,15 +411,16 @@ def _find_project_root():
     return os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
 
 # Simple file logger under Logs/Agent
-def _log_agent(message: str, fname: str = 'agent.log'):
+def _log_agent(message: str, fname: str = 'agent.log', *, scope: Optional[str] = None):
     try:
         log_dir = _agent_logs_root()
         os.makedirs(log_dir, exist_ok=True)
         ts = datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S')
         path = os.path.join(log_dir, fname)
         _rotate_daily(path)
+        line = _format_agent_log_message(message, fname, scope)
         with open(path, 'a', encoding='utf-8') as fh:
-            fh.write(f'[{ts}] {message}\n')
+            fh.write(f'[{ts}] {line}\n')
     except Exception:
         pass
 
@@ -683,6 +735,9 @@ class AgentHttpClient:
         self.key_store = _key_store()
         self.identity = IDENTITY
         self.session = requests.Session()
+        context_label = _agent_context_default()
+        if context_label:
+            self.session.headers.setdefault(_AGENT_CONTEXT_HEADER, context_label)
         self.base_url: Optional[str] = None
         self.guid: Optional[str] = None
         self.access_token: Optional[str] = None
@@ -749,9 +804,13 @@ class AgentHttpClient:
             pass
 
     def auth_headers(self) -> Dict[str, str]:
+        headers: Dict[str, str] = {}
         if self.access_token:
-            return {"Authorization": f"Bearer {self.access_token}"}
-        return {}
+            headers["Authorization"] = f"Bearer {self.access_token}"
+        context_label = _agent_context_default()
+        if context_label:
+            headers[_AGENT_CONTEXT_HEADER] = context_label
+        return headers
 
     def configure_socketio(self, client: "socketio.AsyncClient") -> None:
         """Align the Socket.IO engine's TLS verification with the REST client."""
diff --git a/Data/Server/Modules/admin/routes.py b/Data/Server/Modules/admin/routes.py
index 72c9d81..7268e62 100644
--- a/Data/Server/Modules/admin/routes.py
+++ b/Data/Server/Modules/admin/routes.py
@@ -18,7 +18,7 @@ def register(
     db_conn_factory: Callable[[], sqlite3.Connection],
     require_admin: Callable[[], Optional[Any]],
     current_user: Callable[[], Optional[Dict[str, str]]],
-    log: Callable[[str, str], None],
+    log: Callable[[str, str, Optional[str]], None],
 ) -> None:
     blueprint = Blueprint("admin", __name__)
 
diff --git a/Data/Server/Modules/agents/routes.py b/Data/Server/Modules/agents/routes.py
index 0b96bb2..67f6240 100644
--- a/Data/Server/Modules/agents/routes.py
+++ b/Data/Server/Modules/agents/routes.py
@@ -10,13 +10,24 @@ from flask import Blueprint, jsonify, request, g
 from Modules.auth.device_auth import DeviceAuthManager, require_device_auth
 from Modules.crypto.signing import ScriptSigner
 
+AGENT_CONTEXT_HEADER = "X-Borealis-Agent-Context"
+
+
+def _canonical_context(value: Optional[str]) -> Optional[str]:
+    if not value:
+        return None
+    cleaned = "".join(ch for ch in str(value) if ch.isalnum() or ch in ("_", "-"))
+    if not cleaned:
+        return None
+    return cleaned.upper()
+
 
 def register(
     app,
     *,
     db_conn_factory: Callable[[], Any],
     auth_manager: DeviceAuthManager,
-    log: Callable[[str, str], None],
+    log: Callable[[str, str, Optional[str]], None],
     script_signer: ScriptSigner,
 ) -> None:
     blueprint = Blueprint("agents", __name__)
@@ -29,10 +40,15 @@ def register(
         except Exception:
             return None
 
+    def _context_hint(ctx=None) -> Optional[str]:
+        if ctx is not None and getattr(ctx, "service_mode", None):
+            return _canonical_context(getattr(ctx, "service_mode", None))
+        return _canonical_context(request.headers.get(AGENT_CONTEXT_HEADER))
+
     def _auth_context():
         ctx = getattr(g, "device_auth", None)
         if ctx is None:
-            log("server", f"device auth context missing for {request.path}")
+            log("server", f"device auth context missing for {request.path}", _context_hint())
         return ctx
 
     @blueprint.route("/api/agent/heartbeat", methods=["POST"])
@@ -42,6 +58,7 @@ def register(
         if ctx is None:
             return jsonify({"error": "auth_context_missing"}), 500
         payload = request.get_json(force=True, silent=True) or {}
+        context_label = _context_hint(ctx)
 
         now_ts = int(time.time())
         updates: Dict[str, Optional[str]] = {"last_seen": now_ts}
@@ -111,12 +128,13 @@ def register(
                             "server",
                             "heartbeat hostname collision ignored for guid="
                             f"{ctx.guid}",
+                            context_label,
                         )
                 else:
                     raise
 
             if rowcount == 0:
-                log("server", f"heartbeat missing device record guid={ctx.guid}")
+                log("server", f"heartbeat missing device record guid={ctx.guid}", context_label)
                 return jsonify({"error": "device_not_registered"}), 404
             conn.commit()
         finally:
diff --git a/Data/Server/Modules/auth/device_auth.py b/Data/Server/Modules/auth/device_auth.py
index 177d4b5..4ae1164 100644
--- a/Data/Server/Modules/auth/device_auth.py
+++ b/Data/Server/Modules/auth/device_auth.py
@@ -13,6 +13,17 @@ from flask import g, jsonify, request
 from Modules.auth.dpop import DPoPValidator, DPoPVerificationError, DPoPReplayError
 from Modules.auth.rate_limit import SlidingWindowRateLimiter
 
+AGENT_CONTEXT_HEADER = "X-Borealis-Agent-Context"
+
+
+def _canonical_context(value: Optional[str]) -> Optional[str]:
+    if not value:
+        return None
+    cleaned = "".join(ch for ch in str(value) if ch.isalnum() or ch in ("_", "-"))
+    if not cleaned:
+        return None
+    return cleaned.upper()
+
 
 @dataclass
 class DeviceAuthContext:
@@ -23,6 +34,7 @@ class DeviceAuthContext:
     claims: Dict[str, Any]
     dpop_jkt: Optional[str]
     status: str
+    service_mode: Optional[str]
 
 
 class DeviceAuthError(Exception):
@@ -50,7 +62,7 @@ class DeviceAuthManager:
         db_conn_factory: Callable[[], Any],
         jwt_service,
         dpop_validator: Optional[DPoPValidator],
-        log: Callable[[str, str], None],
+        log: Callable[[str, str, Optional[str]], None],
         rate_limiter: Optional[SlidingWindowRateLimiter] = None,
     ) -> None:
         self._db_conn_factory = db_conn_factory
@@ -89,6 +101,8 @@ class DeviceAuthManager:
                     retry_after=decision.retry_after,
                 )
 
+        context_label = _canonical_context(request.headers.get(AGENT_CONTEXT_HEADER))
+
         conn = self._db_conn_factory()
         try:
             cur = conn.cursor()
@@ -100,10 +114,10 @@ class DeviceAuthManager:
                 """,
                 (guid,),
             )
-            row = cur.fetchone()
+        row = cur.fetchone()
 
-            if not row:
-                row = self._recover_device_record(conn, guid, fingerprint, token_version)
+        if not row:
+            row = self._recover_device_record(conn, guid, fingerprint, token_version, context_label)
         finally:
             conn.close()
 
@@ -127,7 +141,11 @@ class DeviceAuthManager:
         if status_normalized not in allowed_statuses:
             raise DeviceAuthError("device_revoked", status_code=403)
         if status_normalized == "quarantined":
-            self._log("server", f"device {guid} is quarantined; limited access for {request.path}")
+            self._log(
+                "server",
+                f"device {guid} is quarantined; limited access for {request.path}",
+                context_label,
+            )
 
         dpop_jkt: Optional[str] = None
         dpop_proof = request.headers.get("DPoP")
@@ -150,6 +168,7 @@ class DeviceAuthManager:
             claims=claims,
             dpop_jkt=dpop_jkt,
             status=status_normalized,
+            service_mode=context_label,
         )
         return ctx
 
@@ -159,6 +178,7 @@ class DeviceAuthManager:
         guid: str,
         fingerprint: str,
         token_version: int,
+        context_label: Optional[str],
     ) -> Optional[tuple]:
         """Attempt to recreate a missing device row for an authenticated token."""
 
@@ -211,6 +231,7 @@ class DeviceAuthManager:
                 self._log(
                     "server",
                     f"device auth failed to recover guid={guid} due to integrity error: {exc}",
+                    context_label,
                 )
                 conn.rollback()
                 return None
@@ -218,6 +239,7 @@ class DeviceAuthManager:
                 self._log(
                     "server",
                     f"device auth unexpected error recovering guid={guid}: {exc}",
+                    context_label,
                 )
                 conn.rollback()
                 return None
@@ -229,6 +251,7 @@ class DeviceAuthManager:
             self._log(
                 "server",
                 f"device auth could not recover guid={guid}; hostname collisions persisted",
+                context_label,
             )
             conn.rollback()
             return None
@@ -246,6 +269,7 @@ class DeviceAuthManager:
             self._log(
                 "server",
                 f"device auth recovery for guid={guid} committed but row still missing",
+                context_label,
             )
         return row
 
diff --git a/Data/Server/Modules/enrollment/routes.py b/Data/Server/Modules/enrollment/routes.py
index 3392cab..d3fe7de 100644
--- a/Data/Server/Modules/enrollment/routes.py
+++ b/Data/Server/Modules/enrollment/routes.py
@@ -8,6 +8,17 @@ from datetime import datetime, timezone, timedelta
 import time
 from typing import Any, Callable, Dict, Optional, Tuple
 
+AGENT_CONTEXT_HEADER = "X-Borealis-Agent-Context"
+
+
+def _canonical_context(value: Optional[str]) -> Optional[str]:
+    if not value:
+        return None
+    cleaned = "".join(ch for ch in str(value) if ch.isalnum() or ch in ("_", "-"))
+    if not cleaned:
+        return None
+    return cleaned.upper()
+
 from flask import Blueprint, jsonify, request
 
 from Modules.auth.rate_limit import SlidingWindowRateLimiter
@@ -20,7 +31,7 @@ def register(
     app,
     *,
     db_conn_factory: Callable[[], sqlite3.Connection],
-    log: Callable[[str, str], None],
+    log: Callable[[str, str, Optional[str]], None],
     jwt_service,
     tls_bundle_path: str,
     ip_rate_limiter: SlidingWindowRateLimiter,
@@ -51,12 +62,19 @@ def register(
         except Exception:
             return ""
 
-    def _rate_limited(key: str, limiter: SlidingWindowRateLimiter, limit: int, window_s: float):
+    def _rate_limited(
+        key: str,
+        limiter: SlidingWindowRateLimiter,
+        limit: int,
+        window_s: float,
+        context_hint: Optional[str],
+    ):
         decision = limiter.check(key, limit, window_s)
         if not decision.allowed:
             log(
                 "server",
                 f"enrollment rate limited key={key} limit={limit}/{window_s}s retry_after={decision.retry_after:.2f}",
+                context_hint,
             )
             response = jsonify({"error": "rate_limited", "retry_after": decision.retry_after})
             response.status_code = 429
@@ -295,7 +313,9 @@ def register(
     @blueprint.route("/api/agent/enroll/request", methods=["POST"])
     def enrollment_request():
         remote = _remote_addr()
-        rate_error = _rate_limited(f"ip:{remote}", ip_rate_limiter, 40, 60.0)
+        context_hint = _canonical_context(request.headers.get(AGENT_CONTEXT_HEADER))
+
+        rate_error = _rate_limited(f"ip:{remote}", ip_rate_limiter, 40, 60.0, context_hint)
         if rate_error:
             return rate_error
 
@@ -310,42 +330,43 @@ def register(
             "enrollment request received "
             f"ip={remote} hostname={hostname or '<missing>'} code_mask={_mask_code(enrollment_code)} "
             f"pubkey_len={len(agent_pubkey_b64 or '')} nonce_len={len(client_nonce_b64 or '')}",
+            context_hint,
         )
 
         if not hostname:
-            log("server", f"enrollment rejected missing_hostname ip={remote}")
+            log("server", f"enrollment rejected missing_hostname ip={remote}", context_hint)
             return jsonify({"error": "hostname_required"}), 400
         if not enrollment_code:
-            log("server", f"enrollment rejected missing_code ip={remote} host={hostname}")
+            log("server", f"enrollment rejected missing_code ip={remote} host={hostname}", context_hint)
             return jsonify({"error": "enrollment_code_required"}), 400
         if not isinstance(agent_pubkey_b64, str):
-            log("server", f"enrollment rejected missing_pubkey ip={remote} host={hostname}")
+            log("server", f"enrollment rejected missing_pubkey ip={remote} host={hostname}", context_hint)
             return jsonify({"error": "agent_pubkey_required"}), 400
         if not isinstance(client_nonce_b64, str):
-            log("server", f"enrollment rejected missing_nonce ip={remote} host={hostname}")
+            log("server", f"enrollment rejected missing_nonce ip={remote} host={hostname}", context_hint)
             return jsonify({"error": "client_nonce_required"}), 400
 
         try:
             agent_pubkey_der = crypto_keys.spki_der_from_base64(agent_pubkey_b64)
         except Exception:
-            log("server", f"enrollment rejected invalid_pubkey ip={remote} host={hostname}")
+            log("server", f"enrollment rejected invalid_pubkey ip={remote} host={hostname}", context_hint)
             return jsonify({"error": "invalid_agent_pubkey"}), 400
 
         if len(agent_pubkey_der) < 10:
-            log("server", f"enrollment rejected short_pubkey ip={remote} host={hostname}")
+            log("server", f"enrollment rejected short_pubkey ip={remote} host={hostname}", context_hint)
             return jsonify({"error": "invalid_agent_pubkey"}), 400
 
         try:
             client_nonce_bytes = base64.b64decode(client_nonce_b64, validate=True)
         except Exception:
-            log("server", f"enrollment rejected invalid_nonce ip={remote} host={hostname}")
+            log("server", f"enrollment rejected invalid_nonce ip={remote} host={hostname}", context_hint)
             return jsonify({"error": "invalid_client_nonce"}), 400
         if len(client_nonce_bytes) < 16:
-            log("server", f"enrollment rejected short_nonce ip={remote} host={hostname}")
+            log("server", f"enrollment rejected short_nonce ip={remote} host={hostname}", context_hint)
             return jsonify({"error": "invalid_client_nonce"}), 400
 
         fingerprint = crypto_keys.fingerprint_from_spki_der(agent_pubkey_der)
-        rate_error = _rate_limited(f"fp:{fingerprint}", fp_rate_limiter, 12, 60.0)
+        rate_error = _rate_limited(f"fp:{fingerprint}", fp_rate_limiter, 12, 60.0, context_hint)
         if rate_error:
             return rate_error
 
@@ -359,6 +380,7 @@ def register(
                     "server",
                     "enrollment request invalid_code "
                     f"host={hostname} fingerprint={fingerprint[:12]} code_mask={_mask_code(enrollment_code)}",
+                    context_hint,
                 )
                 return jsonify({"error": "invalid_enrollment_code"}), 400
 
@@ -444,7 +466,11 @@ def register(
             "server_certificate": _load_tls_bundle(tls_bundle_path),
             "signing_key": _signing_key_b64(),
         }
-        log("server", f"enrollment request queued fingerprint={fingerprint[:12]} host={hostname} ip={remote}")
+        log(
+            "server",
+            f"enrollment request queued fingerprint={fingerprint[:12]} host={hostname} ip={remote}",
+            context_hint,
+        )
         return jsonify(response)
 
     @blueprint.route("/api/agent/enroll/poll", methods=["POST"])
@@ -453,34 +479,36 @@ def register(
         approval_reference = payload.get("approval_reference")
         client_nonce_b64 = payload.get("client_nonce")
         proof_sig_b64 = payload.get("proof_sig")
+        context_hint = _canonical_context(request.headers.get(AGENT_CONTEXT_HEADER))
 
         log(
             "server",
             "enrollment poll received "
             f"ref={approval_reference} client_nonce_len={len(client_nonce_b64 or '')}"
             f" proof_sig_len={len(proof_sig_b64 or '')}",
+            context_hint,
         )
 
         if not isinstance(approval_reference, str) or not approval_reference:
-            log("server", "enrollment poll rejected missing_reference")
+            log("server", "enrollment poll rejected missing_reference", context_hint)
             return jsonify({"error": "approval_reference_required"}), 400
         if not isinstance(client_nonce_b64, str):
-            log("server", f"enrollment poll rejected missing_nonce ref={approval_reference}")
+            log("server", f"enrollment poll rejected missing_nonce ref={approval_reference}", context_hint)
             return jsonify({"error": "client_nonce_required"}), 400
         if not isinstance(proof_sig_b64, str):
-            log("server", f"enrollment poll rejected missing_sig ref={approval_reference}")
+            log("server", f"enrollment poll rejected missing_sig ref={approval_reference}", context_hint)
             return jsonify({"error": "proof_sig_required"}), 400
 
         try:
             client_nonce_bytes = base64.b64decode(client_nonce_b64, validate=True)
         except Exception:
-            log("server", f"enrollment poll invalid_client_nonce ref={approval_reference}")
+            log("server", f"enrollment poll invalid_client_nonce ref={approval_reference}", context_hint)
             return jsonify({"error": "invalid_client_nonce"}), 400
 
         try:
             proof_sig = base64.b64decode(proof_sig_b64, validate=True)
         except Exception:
-            log("server", f"enrollment poll invalid_sig ref={approval_reference}")
+            log("server", f"enrollment poll invalid_sig ref={approval_reference}", context_hint)
             return jsonify({"error": "invalid_proof_sig"}), 400
 
         conn = db_conn_factory()
@@ -498,7 +526,7 @@ def register(
             )
             row = cur.fetchone()
             if not row:
-                log("server", f"enrollment poll unknown_reference ref={approval_reference}")
+                log("server", f"enrollment poll unknown_reference ref={approval_reference}", context_hint)
                 return jsonify({"status": "unknown"}), 404
 
             (
@@ -517,13 +545,13 @@ def register(
             ) = row
 
             if client_nonce_stored != client_nonce_b64:
-                log("server", f"enrollment poll nonce_mismatch ref={approval_reference}")
+                log("server", f"enrollment poll nonce_mismatch ref={approval_reference}", context_hint)
                 return jsonify({"error": "nonce_mismatch"}), 400
 
             try:
                 server_nonce_bytes = base64.b64decode(server_nonce_b64, validate=True)
             except Exception:
-                log("server", f"enrollment poll invalid_server_nonce ref={approval_reference}")
+                log("server", f"enrollment poll invalid_server_nonce ref={approval_reference}", context_hint)
                 return jsonify({"error": "server_nonce_invalid"}), 400
 
             message = server_nonce_bytes + approval_reference.encode("utf-8") + client_nonce_bytes
@@ -531,17 +559,17 @@ def register(
             try:
                 public_key = serialization.load_der_public_key(agent_pubkey_der)
             except Exception:
-                log("server", f"enrollment poll pubkey_load_failed ref={approval_reference}")
+                log("server", f"enrollment poll pubkey_load_failed ref={approval_reference}", context_hint)
                 public_key = None
 
             if public_key is None:
-                log("server", f"enrollment poll invalid_pubkey ref={approval_reference}")
+                log("server", f"enrollment poll invalid_pubkey ref={approval_reference}", context_hint)
                 return jsonify({"error": "agent_pubkey_invalid"}), 400
 
             try:
                 public_key.verify(proof_sig, message)
             except Exception:
-                log("server", f"enrollment poll invalid_proof ref={approval_reference}")
+                log("server", f"enrollment poll invalid_proof ref={approval_reference}", context_hint)
                 return jsonify({"error": "invalid_proof"}), 400
 
             if status == "pending":
@@ -549,24 +577,28 @@ def register(
                     "server",
                     f"enrollment poll pending ref={approval_reference} host={hostname_claimed}"
                     f" fingerprint={fingerprint[:12]}",
+                    context_hint,
                 )
                 return jsonify({"status": "pending", "poll_after_ms": 5000})
             if status == "denied":
                 log(
                     "server",
                     f"enrollment poll denied ref={approval_reference} host={hostname_claimed}",
+                    context_hint,
                 )
                 return jsonify({"status": "denied", "reason": "operator_denied"})
             if status == "expired":
                 log(
                     "server",
                     f"enrollment poll expired ref={approval_reference} host={hostname_claimed}",
+                    context_hint,
                 )
                 return jsonify({"status": "expired"})
             if status == "completed":
                 log(
                     "server",
                     f"enrollment poll already_completed ref={approval_reference} host={hostname_claimed}",
+                    context_hint,
                 )
                 return jsonify({"status": "approved", "detail": "finalized"})
 
@@ -574,6 +606,7 @@ def register(
                 log(
                     "server",
                     f"enrollment poll unexpected_status={status} ref={approval_reference}",
+                    context_hint,
                 )
                 return jsonify({"status": status or "unknown"}), 400
 
@@ -582,6 +615,7 @@ def register(
                 log(
                     "server",
                     f"enrollment poll replay_detected ref={approval_reference} fingerprint={fingerprint[:12]}",
+                    context_hint,
                 )
                 return jsonify({"error": "proof_replayed"}), 409
 
@@ -656,6 +690,7 @@ def register(
         log(
             "server",
             f"enrollment finalized guid={effective_guid} fingerprint={fingerprint[:12]} host={hostname_claimed}",
+            context_hint,
         )
         return jsonify(
             {
diff --git a/Data/Server/Modules/jobs/prune.py b/Data/Server/Modules/jobs/prune.py
index 2e6e21e..bc9f18e 100644
--- a/Data/Server/Modules/jobs/prune.py
+++ b/Data/Server/Modules/jobs/prune.py
@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from datetime import datetime, timedelta, timezone
-from typing import Callable
+from typing import Callable, Optional
 
 import eventlet
 from flask_socketio import SocketIO
@@ -11,7 +11,7 @@ def start_prune_job(
     socketio: SocketIO,
     *,
     db_conn_factory: Callable[[], any],
-    log: Callable[[str, str], None],
+    log: Callable[[str, str, Optional[str]], None],
 ) -> None:
     def _job_loop():
         while True:
@@ -24,7 +24,7 @@ def start_prune_job(
     socketio.start_background_task(_job_loop)
 
 
-def _run_once(db_conn_factory: Callable[[], any], log: Callable[[str, str], None]) -> None:
+def _run_once(db_conn_factory: Callable[[], any], log: Callable[[str, str, Optional[str]], None]) -> None:
     now = datetime.now(tz=timezone.utc)
     now_iso = now.isoformat()
     stale_before = (now - timedelta(hours=24)).isoformat()
diff --git a/Data/Server/server.py b/Data/Server/server.py
index 346562d..f0cdc63 100644
--- a/Data/Server/server.py
+++ b/Data/Server/server.py
@@ -152,15 +152,62 @@ def _rotate_daily(path: str):
         pass
 
 
-def _write_service_log(service: str, msg: str):
+_SERVER_SCOPE_PATTERN = re.compile(r"\\b(?:scope|context|agent_context)=([A-Za-z0-9_-]+)", re.IGNORECASE)
+_SERVER_AGENT_ID_PATTERN = re.compile(r"\\bagent_id=([^\s,]+)", re.IGNORECASE)
+_AGENT_CONTEXT_HEADER = "X-Borealis-Agent-Context"
+
+
+def _canonical_server_scope(raw: Optional[str]) -> Optional[str]:
+    if not raw:
+        return None
+    value = "".join(ch for ch in str(raw) if ch.isalnum() or ch in ("_", "-"))
+    if not value:
+        return None
+    return value.upper()
+
+
+def _scope_from_agent_id(agent_id: Optional[str]) -> Optional[str]:
+    candidate = _canonical_server_scope(agent_id)
+    if not candidate:
+        return None
+    if candidate.endswith("_SYSTEM"):
+        return "SYSTEM"
+    if candidate.endswith("_CURRENTUSER"):
+        return "CURRENTUSER"
+    return candidate
+
+
+def _infer_server_scope(message: str, explicit: Optional[str]) -> Optional[str]:
+    scope = _canonical_server_scope(explicit)
+    if scope:
+        return scope
+    match = _SERVER_SCOPE_PATTERN.search(message or "")
+    if match:
+        scope = _canonical_server_scope(match.group(1))
+        if scope:
+            return scope
+    agent_match = _SERVER_AGENT_ID_PATTERN.search(message or "")
+    if agent_match:
+        scope = _scope_from_agent_id(agent_match.group(1))
+        if scope:
+            return scope
+    return None
+
+
+def _write_service_log(service: str, msg: str, scope: Optional[str] = None, *, level: str = "INFO"):
     try:
         base = _server_logs_root()
         os.makedirs(base, exist_ok=True)
         path = os.path.join(base, f"{service}.log")
         _rotate_daily(path)
         ts = time.strftime('%Y-%m-%d %H:%M:%S')
+        resolved_scope = _infer_server_scope(msg, scope)
+        prefix_parts = [f"[{level.upper()}]"]
+        if resolved_scope:
+            prefix_parts.append(f"[CONTEXT-{resolved_scope}]")
+        prefix = "".join(prefix_parts)
         with open(path, 'a', encoding='utf-8') as fh:
-            fh.write(f'[{ts}] {msg}\n')
+            fh.write(f'[{ts}] {prefix} {msg}\n')
     except Exception:
         pass
 

From 0ecbc30ad80432fee2258372e5809969a7b81d48 Mon Sep 17 00:00:00 2001
From: Nicole Rappe <nicole.rappe@bunny-lab.io>
Date: Sat, 18 Oct 2025 04:07:28 -0600
Subject: [PATCH 05/14] Fix device auth recovery try block

---
 Data/Server/Modules/auth/device_auth.py | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/Data/Server/Modules/auth/device_auth.py b/Data/Server/Modules/auth/device_auth.py
index 4ae1164..9e2181d 100644
--- a/Data/Server/Modules/auth/device_auth.py
+++ b/Data/Server/Modules/auth/device_auth.py
@@ -114,10 +114,12 @@ class DeviceAuthManager:
                 """,
                 (guid,),
             )
-        row = cur.fetchone()
+            row = cur.fetchone()
 
-        if not row:
-            row = self._recover_device_record(conn, guid, fingerprint, token_version, context_label)
+            if not row:
+                row = self._recover_device_record(
+                    conn, guid, fingerprint, token_version, context_label
+                )
         finally:
             conn.close()
 

From 051fc81c8a452ec78ca141be276d985f5edb8340 Mon Sep 17 00:00:00 2001
From: Nicole Rappe <nicole.rappe@bunny-lab.io>
Date: Sat, 18 Oct 2025 04:10:27 -0600
Subject: [PATCH 06/14] Use context manager for device auth lookup

---
 Data/Server/Modules/auth/device_auth.py | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/Data/Server/Modules/auth/device_auth.py b/Data/Server/Modules/auth/device_auth.py
index 9e2181d..1a45820 100644
--- a/Data/Server/Modules/auth/device_auth.py
+++ b/Data/Server/Modules/auth/device_auth.py
@@ -3,6 +3,7 @@ from __future__ import annotations
 import functools
 import sqlite3
 import time
+from contextlib import closing
 from dataclasses import dataclass
 from datetime import datetime, timezone
 from typing import Any, Callable, Dict, Optional
@@ -103,8 +104,7 @@ class DeviceAuthManager:
 
         context_label = _canonical_context(request.headers.get(AGENT_CONTEXT_HEADER))
 
-        conn = self._db_conn_factory()
-        try:
+        with closing(self._db_conn_factory()) as conn:
             cur = conn.cursor()
             cur.execute(
                 """
@@ -120,8 +120,6 @@ class DeviceAuthManager:
                 row = self._recover_device_record(
                     conn, guid, fingerprint, token_version, context_label
                 )
-        finally:
-            conn.close()
 
         if not row:
             raise DeviceAuthError("device_not_found", status_code=403)

From 60a8cfcdc0c8888c59fee8e3807f12f1805776d8 Mon Sep 17 00:00:00 2001
From: Nicole Rappe <nicole.rappe@bunny-lab.io>
Date: Sat, 18 Oct 2025 04:23:48 -0600
Subject: [PATCH 07/14] Improve websocket TLS configuration and error logging

---
 Data/Agent/agent.py | 53 +++++++++++++++++++++++++++++++++++----------
 1 file changed, 41 insertions(+), 12 deletions(-)

diff --git a/Data/Agent/agent.py b/Data/Agent/agent.py
index e6e1112..898189e 100644
--- a/Data/Agent/agent.py
+++ b/Data/Agent/agent.py
@@ -129,6 +129,33 @@ def _bootstrap_log(msg: str, *, scope: Optional[str] = None):
     except Exception:
         pass
 
+
+def _describe_exception(exc: BaseException) -> str:
+    try:
+        primary = f"{exc.__class__.__name__}: {exc}"
+    except Exception:
+        primary = repr(exc)
+    parts = [primary]
+    try:
+        cause = getattr(exc, "__cause__", None)
+        if cause and cause is not exc:
+            parts.append(f"cause={cause.__class__.__name__}: {cause}")
+    except Exception:
+        pass
+    try:
+        context = getattr(exc, "__context__", None)
+        if context and context is not exc and context is not getattr(exc, "__cause__", None):
+            parts.append(f"context={context.__class__.__name__}: {context}")
+    except Exception:
+        pass
+    try:
+        args = getattr(exc, "args", None)
+        if isinstance(args, tuple) and len(args) > 1:
+            parts.append(f"args={args!r}")
+    except Exception:
+        pass
+    return "; ".join(part for part in parts if part)
+
 # Headless/service mode flag (skip Qt and interactive UI)
 SYSTEM_SERVICE_MODE = ('--system-service' in sys.argv) or (os.environ.get('BOREALIS_AGENT_MODE') == 'system')
 SERVICE_MODE = 'system' if SYSTEM_SERVICE_MODE else 'currentuser'
@@ -820,22 +847,23 @@ class AgentHttpClient:
             if engine is None:
                 return
 
-            # python-engineio accepts either a boolean or an ``ssl.SSLContext``
-            # for TLS verification.  When we have a pinned certificate bundle
-            # on disk, prefer constructing a dedicated context that trusts that
-            # bundle so WebSocket connections succeed even with private CAs.
+            # python-engineio accepts either a boolean, a path to a CA bundle,
+            # or an ``ssl.SSLContext`` for TLS verification.  When we have a
+            # pinned certificate bundle on disk, prefer constructing a context
+            # that trusts that bundle, while also passing the explicit path so
+            # the engine falls back to the same trust store if it rebuilds the
+            # context internally.  This ensures SYSTEM services that rely on
+            # machine-scoped certificates can negotiate WebSocket TLS without
+            # tripping over default CA roots.
             if isinstance(verify, str) and os.path.isfile(verify):
+                context = None
                 try:
                     context = ssl.create_default_context(cafile=verify)
                     context.check_hostname = False
                 except Exception:
                     context = None
-                if context is not None:
-                    engine.ssl_context = context
-                    engine.ssl_verify = True
-                else:
-                    engine.ssl_context = None
-                    engine.ssl_verify = verify
+                engine.ssl_context = context
+                engine.ssl_verify = verify
             elif verify is False:
                 engine.ssl_context = None
                 engine.ssl_verify = False
@@ -2598,8 +2626,9 @@ async def connect_loop():
             )
             break
         except Exception as e:
-            print(f"[WebSocket] Server unavailable: {e}. Retrying in {retry}s...")
-            _log_agent(f'Server unavailable: {e}', fname='agent.error.log')
+            detail = _describe_exception(e)
+            print(f"[WebSocket] Server unavailable: {detail}. Retrying in {retry}s...")
+            _log_agent(f'Server unavailable: {detail}', fname='agent.error.log')
             await asyncio.sleep(retry)
 
 if __name__=='__main__':

From 10c43c431eb2e6e1e0dfb31671e8cb2b76e63372 Mon Sep 17 00:00:00 2001
From: Nicole Rappe <nicole.rappe@bunny-lab.io>
Date: Sat, 18 Oct 2025 04:36:30 -0600
Subject: [PATCH 08/14] Improve socket.io TLS alignment and logging

---
 Data/Agent/agent.py | 63 +++++++++++++++++++++++++++------------------
 1 file changed, 38 insertions(+), 25 deletions(-)

diff --git a/Data/Agent/agent.py b/Data/Agent/agent.py
index 898189e..74c6901 100644
--- a/Data/Agent/agent.py
+++ b/Data/Agent/agent.py
@@ -839,39 +839,41 @@ class AgentHttpClient:
             headers[_AGENT_CONTEXT_HEADER] = context_label
         return headers
 
-    def configure_socketio(self, client: "socketio.AsyncClient") -> None:
-        """Align the Socket.IO engine's TLS verification with the REST client."""
+    def configure_socketio(self, client: "socketio.AsyncClient") -> Dict[str, Any]:
+        """Align Socket.IO TLS settings with the REST session and return connect kwargs."""
+
+        connect_kwargs: Dict[str, Any] = {}
         try:
             verify = getattr(self.session, "verify", True)
-            engine = getattr(client, "eio", None)
-            if engine is None:
-                return
-
-            # python-engineio accepts either a boolean, a path to a CA bundle,
-            # or an ``ssl.SSLContext`` for TLS verification.  When we have a
-            # pinned certificate bundle on disk, prefer constructing a context
-            # that trusts that bundle, while also passing the explicit path so
-            # the engine falls back to the same trust store if it rebuilds the
-            # context internally.  This ensures SYSTEM services that rely on
-            # machine-scoped certificates can negotiate WebSocket TLS without
-            # tripping over default CA roots.
+            context = None
             if isinstance(verify, str) and os.path.isfile(verify):
-                context = None
                 try:
                     context = ssl.create_default_context(cafile=verify)
                     context.check_hostname = False
                 except Exception:
                     context = None
-                engine.ssl_context = context
-                engine.ssl_verify = verify
-            elif verify is False:
-                engine.ssl_context = None
-                engine.ssl_verify = False
-            else:
-                engine.ssl_context = None
-                engine.ssl_verify = True
+            if context is not None:
+                connect_kwargs["ssl_context"] = context
+
+            # The AsyncClient honours ``ssl_verify`` / ``ssl_context`` parameters
+            # passed to ``connect``.  For compatibility with older engineio builds
+            # we also reflect the values onto the underlying engine instance when
+            # available so reconnect attempts use the same trust material.
+            connect_kwargs["ssl_verify"] = verify
+
+            engine = getattr(client, "eio", None)
+            if engine is not None:
+                try:
+                    engine.ssl_context = connect_kwargs.get("ssl_context")
+                except Exception:
+                    pass
+                try:
+                    engine.ssl_verify = verify
+                except Exception:
+                    pass
         except Exception:
-            pass
+            connect_kwargs.setdefault("ssl_verify", True)
+        return connect_kwargs
 
     # ------------------------------------------------------------------
     # Enrollment & token management
@@ -2615,7 +2617,11 @@ async def connect_loop():
     while True:
         try:
             client.ensure_authenticated()
-            client.configure_socketio(sio)
+            connect_kwargs = client.configure_socketio(sio) or {}
+            try:
+                setattr(sio, "connection_error", None)
+            except Exception:
+                pass
             url = client.websocket_base_url()
             print(f"[INFO] Connecting Agent to {url}...")
             _log_agent(f'Connecting to {url}...')
@@ -2623,10 +2629,17 @@ async def connect_loop():
                 url,
                 transports=['websocket'],
                 headers=client.auth_headers(),
+                **connect_kwargs,
             )
             break
         except Exception as e:
             detail = _describe_exception(e)
+            try:
+                conn_err = getattr(sio, "connection_error", None)
+            except Exception:
+                conn_err = None
+            if conn_err:
+                detail = f"{detail}; connection_error={conn_err!r}"
             print(f"[WebSocket] Server unavailable: {detail}. Retrying in {retry}s...")
             _log_agent(f'Server unavailable: {detail}', fname='agent.error.log')
             await asyncio.sleep(retry)

From 783c041bf6228b5528198f2bad65e3212bc6a5f0 Mon Sep 17 00:00:00 2001
From: Nicole Rappe <nicole.rappe@bunny-lab.io>
Date: Sat, 18 Oct 2025 04:45:21 -0600
Subject: [PATCH 09/14] Fix Socket.IO TLS kwargs for legacy client

---
 Data/Agent/agent.py | 39 ++++++++++++++++++++++++---------------
 1 file changed, 24 insertions(+), 15 deletions(-)

diff --git a/Data/Agent/agent.py b/Data/Agent/agent.py
index 74c6901..b8a4137 100644
--- a/Data/Agent/agent.py
+++ b/Data/Agent/agent.py
@@ -845,34 +845,43 @@ class AgentHttpClient:
         connect_kwargs: Dict[str, Any] = {}
         try:
             verify = getattr(self.session, "verify", True)
+            ssl_value: Any
             context = None
-            if isinstance(verify, str) and os.path.isfile(verify):
+
+            if isinstance(verify, bool):
+                ssl_value = verify
+            elif isinstance(verify, str) and os.path.isfile(verify):
                 try:
                     context = ssl.create_default_context(cafile=verify)
                     context.check_hostname = False
+                    ssl_value = context
                 except Exception:
-                    context = None
-            if context is not None:
-                connect_kwargs["ssl_context"] = context
+                    ssl_value = True
+            else:
+                ssl_value = True
 
-            # The AsyncClient honours ``ssl_verify`` / ``ssl_context`` parameters
-            # passed to ``connect``.  For compatibility with older engineio builds
-            # we also reflect the values onto the underlying engine instance when
-            # available so reconnect attempts use the same trust material.
-            connect_kwargs["ssl_verify"] = verify
+            connect_kwargs["ssl"] = ssl_value
 
             engine = getattr(client, "eio", None)
             if engine is not None:
                 try:
-                    engine.ssl_context = connect_kwargs.get("ssl_context")
-                except Exception:
-                    pass
-                try:
-                    engine.ssl_verify = verify
+                    setattr(engine, "ssl", ssl_value)
                 except Exception:
                     pass
+                if context is not None:
+                    for attr in ("ssl_context", "ssl_verify"):
+                        try:
+                            setattr(engine, attr, context if attr == "ssl_context" else True)
+                        except Exception:
+                            pass
+                elif isinstance(ssl_value, bool):
+                    for attr in ("ssl_verify", "ssl_context"):
+                        try:
+                            setattr(engine, attr, ssl_value if attr == "ssl_verify" else None)
+                        except Exception:
+                            pass
         except Exception:
-            connect_kwargs.setdefault("ssl_verify", True)
+            connect_kwargs.setdefault("ssl", True)
         return connect_kwargs
 
     # ------------------------------------------------------------------

From cab5581ad2e0fcb832f7dfa86ddf8e7d08352fee Mon Sep 17 00:00:00 2001
From: Nicole Rappe <nicole.rappe@bunny-lab.io>
Date: Sat, 18 Oct 2025 04:57:48 -0600
Subject: [PATCH 10/14] Remove unsupported Socket.IO TLS kwargs

---
 Data/Agent/agent.py | 62 +++++++++++++++++++++------------------------
 1 file changed, 29 insertions(+), 33 deletions(-)

diff --git a/Data/Agent/agent.py b/Data/Agent/agent.py
index b8a4137..317d109 100644
--- a/Data/Agent/agent.py
+++ b/Data/Agent/agent.py
@@ -839,50 +839,47 @@ class AgentHttpClient:
             headers[_AGENT_CONTEXT_HEADER] = context_label
         return headers
 
-    def configure_socketio(self, client: "socketio.AsyncClient") -> Dict[str, Any]:
-        """Align Socket.IO TLS settings with the REST session and return connect kwargs."""
+    def configure_socketio(self, client: "socketio.AsyncClient") -> None:
+        """Align the Socket.IO engine's TLS verification with the REST client."""
 
-        connect_kwargs: Dict[str, Any] = {}
         try:
             verify = getattr(self.session, "verify", True)
-            ssl_value: Any
-            context = None
+            engine = getattr(client, "eio", None)
+            if engine is None:
+                return
 
-            if isinstance(verify, bool):
-                ssl_value = verify
-            elif isinstance(verify, str) and os.path.isfile(verify):
+            context = None
+            if isinstance(verify, str) and os.path.isfile(verify):
                 try:
                     context = ssl.create_default_context(cafile=verify)
                     context.check_hostname = False
-                    ssl_value = context
                 except Exception:
-                    ssl_value = True
-            else:
-                ssl_value = True
+                    context = None
 
-            connect_kwargs["ssl"] = ssl_value
-
-            engine = getattr(client, "eio", None)
-            if engine is not None:
+            if context is not None:
                 try:
-                    setattr(engine, "ssl", ssl_value)
+                    engine.ssl_context = context
                 except Exception:
                     pass
-                if context is not None:
-                    for attr in ("ssl_context", "ssl_verify"):
-                        try:
-                            setattr(engine, attr, context if attr == "ssl_context" else True)
-                        except Exception:
-                            pass
-                elif isinstance(ssl_value, bool):
-                    for attr in ("ssl_verify", "ssl_context"):
-                        try:
-                            setattr(engine, attr, ssl_value if attr == "ssl_verify" else None)
-                        except Exception:
-                            pass
+                try:
+                    engine.ssl_verify = True
+                except Exception:
+                    pass
+                return
+
+            # Fall back to boolean verification flags when we either do not
+            # have a pinned certificate bundle or failed to build a dedicated
+            # context for it.
+            try:
+                engine.ssl_context = None
+            except Exception:
+                pass
+            try:
+                engine.ssl_verify = False if verify is False else True
+            except Exception:
+                pass
         except Exception:
-            connect_kwargs.setdefault("ssl", True)
-        return connect_kwargs
+            pass
 
     # ------------------------------------------------------------------
     # Enrollment & token management
@@ -2626,7 +2623,7 @@ async def connect_loop():
     while True:
         try:
             client.ensure_authenticated()
-            connect_kwargs = client.configure_socketio(sio) or {}
+            client.configure_socketio(sio)
             try:
                 setattr(sio, "connection_error", None)
             except Exception:
@@ -2638,7 +2635,6 @@ async def connect_loop():
                 url,
                 transports=['websocket'],
                 headers=client.auth_headers(),
-                **connect_kwargs,
             )
             break
         except Exception as e:

From 87fffb1f47ff4b58552295f381ea9c001d361b98 Mon Sep 17 00:00:00 2001
From: Nicole Rappe <nicole.rappe@bunny-lab.io>
Date: Sat, 18 Oct 2025 05:08:00 -0600
Subject: [PATCH 11/14] Fix Socket.IO TLS alignment

---
 Data/Agent/agent.py | 61 +++++++++++++++++++++++++++++++++------------
 1 file changed, 45 insertions(+), 16 deletions(-)

diff --git a/Data/Agent/agent.py b/Data/Agent/agent.py
index 317d109..6c63a27 100644
--- a/Data/Agent/agent.py
+++ b/Data/Agent/agent.py
@@ -848,6 +848,25 @@ class AgentHttpClient:
             if engine is None:
                 return
 
+            http_iface = getattr(engine, "http", None)
+
+            def _set_attr(target: Any, name: str, value: Any) -> None:
+                if target is None:
+                    return
+                try:
+                    setattr(target, name, value)
+                except Exception:
+                    pass
+
+            def _reset_cached_session() -> None:
+                if http_iface is None:
+                    return
+                try:
+                    if hasattr(http_iface, "session"):
+                        setattr(http_iface, "session", None)
+                except Exception:
+                    pass
+
             context = None
             if isinstance(verify, str) and os.path.isfile(verify):
                 try:
@@ -857,27 +876,26 @@ class AgentHttpClient:
                     context = None
 
             if context is not None:
-                try:
-                    engine.ssl_context = context
-                except Exception:
-                    pass
-                try:
-                    engine.ssl_verify = True
-                except Exception:
-                    pass
+                _set_attr(engine, "ssl_context", context)
+                _set_attr(engine, "ssl_verify", True)
+                _set_attr(engine, "verify_ssl", True)
+                _set_attr(http_iface, "ssl_context", context)
+                _set_attr(http_iface, "ssl_verify", True)
+                _set_attr(http_iface, "verify_ssl", True)
+                _reset_cached_session()
                 return
 
             # Fall back to boolean verification flags when we either do not
             # have a pinned certificate bundle or failed to build a dedicated
             # context for it.
-            try:
-                engine.ssl_context = None
-            except Exception:
-                pass
-            try:
-                engine.ssl_verify = False if verify is False else True
-            except Exception:
-                pass
+            verify_flag = False if verify is False else True
+            _set_attr(engine, "ssl_context", None)
+            _set_attr(engine, "ssl_verify", verify_flag)
+            _set_attr(engine, "verify_ssl", verify_flag)
+            _set_attr(http_iface, "ssl_context", None)
+            _set_attr(http_iface, "ssl_verify", verify_flag)
+            _set_attr(http_iface, "verify_ssl", verify_flag)
+            _reset_cached_session()
         except Exception:
             pass
 
@@ -2373,6 +2391,17 @@ async def connect():
     except Exception:
         pass
 
+@sio.event
+async def connect_error(data):
+    try:
+        setattr(sio, "connection_error", data)
+    except Exception:
+        pass
+    try:
+        _log_agent(f'Socket connect_error event: {data!r}', fname='agent.error.log')
+    except Exception:
+        pass
+
 @sio.event
 async def disconnect():
     print("[WebSocket] Disconnected from Borealis server.")

From 3a71cc4c42993cab4b516e3496ba65bcea12bee7 Mon Sep 17 00:00:00 2001
From: Nicole Rappe <nicole.rappe@bunny-lab.io>
Date: Sat, 18 Oct 2025 05:25:08 -0600
Subject: [PATCH 12/14] Expand agent/server websocket diagnostics

---
 Data/Agent/agent.py   | 131 ++++++++++++++++++++++++++++++++++++++++--
 Data/Server/server.py |  96 ++++++++++++++++++++++++++++++-
 2 files changed, 221 insertions(+), 6 deletions(-)

diff --git a/Data/Agent/agent.py b/Data/Agent/agent.py
index 6c63a27..aaaa749 100644
--- a/Data/Agent/agent.py
+++ b/Data/Agent/agent.py
@@ -154,8 +154,29 @@ def _describe_exception(exc: BaseException) -> str:
             parts.append(f"args={args!r}")
     except Exception:
         pass
+    try:
+        details = getattr(exc, "__dict__", None)
+        if isinstance(details, dict):
+            # Capture noteworthy nested attributes such as os_error/errno to help diagnose
+            # connection failures that collapse into generic ConnectionError wrappers.
+            for key in ("os_error", "errno", "code", "status"):
+                if key in details and details[key]:
+                    parts.append(f"{key}={details[key]!r}")
+    except Exception:
+        pass
     return "; ".join(part for part in parts if part)
 
+
+def _log_exception_trace(prefix: str) -> None:
+    try:
+        tb = traceback.format_exc()
+        if not tb:
+            return
+        for line in tb.rstrip().splitlines():
+            _log_agent(f"{prefix} trace: {line}", fname="agent.error.log")
+    except Exception:
+        pass
+
 # Headless/service mode flag (skip Qt and interactive UI)
 SYSTEM_SERVICE_MODE = ('--system-service' in sys.argv) or (os.environ.get('BOREALIS_AGENT_MODE') == 'system')
 SERVICE_MODE = 'system' if SYSTEM_SERVICE_MODE else 'currentuser'
@@ -464,6 +485,31 @@ def _mask_sensitive(value: str, *, prefix: int = 4, suffix: int = 4) -> str:
         return '***'
 
 
+def _format_debug_pairs(pairs: Dict[str, Any]) -> str:
+    try:
+        parts = []
+        for key, value in pairs.items():
+            parts.append(f"{key}={value!r}")
+        return ", ".join(parts)
+    except Exception:
+        return repr(pairs)
+
+
+def _summarize_headers(headers: Dict[str, str]) -> str:
+    try:
+        rendered: List[str] = []
+        for key, value in headers.items():
+            lowered = key.lower()
+            display = value
+            if lowered == 'authorization':
+                token = value.split()[-1] if value and ' ' in value else value
+                display = f"Bearer {_mask_sensitive(token)}"
+            rendered.append(f"{key}={display}")
+        return ", ".join(rendered)
+    except Exception:
+        return '<unavailable>'
+
+
 def _decode_base64_text(value):
     if not isinstance(value, str):
         return None
@@ -846,10 +892,25 @@ class AgentHttpClient:
             verify = getattr(self.session, "verify", True)
             engine = getattr(client, "eio", None)
             if engine is None:
+                _log_agent(
+                    "SocketIO TLS alignment skipped; AsyncClient.eio missing",
+                    fname="agent.error.log",
+                )
                 return
 
             http_iface = getattr(engine, "http", None)
 
+            debug_info = {
+                "verify_type": type(verify).__name__,
+                "verify_value": verify,
+                "engine_type": type(engine).__name__,
+                "http_iface_present": http_iface is not None,
+            }
+            _log_agent(
+                f"SocketIO TLS alignment start: {_format_debug_pairs(debug_info)}",
+                fname="agent.log",
+            )
+
             def _set_attr(target: Any, name: str, value: Any) -> None:
                 if target is None:
                     return
@@ -872,8 +933,16 @@ class AgentHttpClient:
                 try:
                     context = ssl.create_default_context(cafile=verify)
                     context.check_hostname = False
+                    _log_agent(
+                        f"SocketIO TLS alignment created SSLContext from cafile={verify}",
+                        fname="agent.log",
+                    )
                 except Exception:
                     context = None
+                    _log_agent(
+                        f"SocketIO TLS alignment failed to build context from cafile={verify}",
+                        fname="agent.error.log",
+                    )
 
             if context is not None:
                 _set_attr(engine, "ssl_context", context)
@@ -883,6 +952,10 @@ class AgentHttpClient:
                 _set_attr(http_iface, "ssl_verify", True)
                 _set_attr(http_iface, "verify_ssl", True)
                 _reset_cached_session()
+                _log_agent(
+                    "SocketIO TLS alignment applied dedicated SSLContext to engine/http",
+                    fname="agent.log",
+                )
                 return
 
             # Fall back to boolean verification flags when we either do not
@@ -896,8 +969,16 @@ class AgentHttpClient:
             _set_attr(http_iface, "ssl_verify", verify_flag)
             _set_attr(http_iface, "verify_ssl", verify_flag)
             _reset_cached_session()
+            _log_agent(
+                f"SocketIO TLS alignment fallback verify_flag={verify_flag}",
+                fname="agent.log",
+            )
         except Exception:
-            pass
+            _log_agent(
+                "SocketIO TLS alignment encountered unexpected error",
+                fname="agent.error.log",
+            )
+            _log_exception_trace("configure_socketio")
 
     # ------------------------------------------------------------------
     # Enrollment & token management
@@ -2355,6 +2436,15 @@ async def send_agent_details_once():
 async def connect():
     print(f"[INFO] Successfully Connected to Borealis Server!")
     _log_agent('Connected to server.')
+    try:
+        sid = getattr(sio, 'sid', None)
+        transport = getattr(sio, 'transport', None)
+        _log_agent(
+            f'WebSocket handshake established sid={sid!r} transport={transport!r}',
+            fname='agent.log',
+        )
+    except Exception:
+        pass
     await sio.emit('connect_agent', {"agent_id": AGENT_ID, "service_mode": SERVICE_MODE})
 
     # Send an immediate heartbeat via authenticated REST call.
@@ -2649,21 +2739,47 @@ if not SYSTEM_SERVICE_MODE:
 async def connect_loop():
     retry = 5
     client = http_client()
+    attempt = 0
     while True:
+        attempt += 1
         try:
+            _log_agent(
+                f'connect_loop attempt={attempt} starting authentication phase',
+                fname='agent.log',
+            )
             client.ensure_authenticated()
+            auth_snapshot = {
+                'guid_present': bool(client.guid),
+                'access_token': bool(client.access_token),
+                'refresh_token': bool(client.refresh_token),
+                'access_expiry': client.access_expires_at,
+            }
+            _log_agent(
+                f"connect_loop attempt={attempt} auth snapshot: {_format_debug_pairs(auth_snapshot)}",
+                fname='agent.log',
+            )
             client.configure_socketio(sio)
             try:
                 setattr(sio, "connection_error", None)
             except Exception:
                 pass
             url = client.websocket_base_url()
+            headers = client.auth_headers()
+            header_summary = _summarize_headers(headers)
+            verify_value = getattr(client.session, 'verify', None)
+            _log_agent(
+                f"connect_loop attempt={attempt} dialing websocket url={url} transports=['websocket'] verify={verify_value!r} headers={header_summary}",
+                fname='agent.log',
+            )
             print(f"[INFO] Connecting Agent to {url}...")
-            _log_agent(f'Connecting to {url}...')
             await sio.connect(
                 url,
                 transports=['websocket'],
-                headers=client.auth_headers(),
+                headers=headers,
+            )
+            _log_agent(
+                f'connect_loop attempt={attempt} sio.connect completed successfully',
+                fname='agent.log',
             )
             break
         except Exception as e:
@@ -2674,8 +2790,13 @@ async def connect_loop():
                 conn_err = None
             if conn_err:
                 detail = f"{detail}; connection_error={conn_err!r}"
-            print(f"[WebSocket] Server unavailable: {detail}. Retrying in {retry}s...")
-            _log_agent(f'Server unavailable: {detail}', fname='agent.error.log')
+            message = (
+                f"connect_loop attempt={attempt} server unavailable: {detail}. "
+                f"Retrying in {retry}s..."
+            )
+            print(f"[WebSocket] {message}")
+            _log_agent(message, fname='agent.error.log')
+            _log_exception_trace(f'connect_loop attempt={attempt}')
             await asyncio.sleep(retry)
 
 if __name__=='__main__':
diff --git a/Data/Server/server.py b/Data/Server/server.py
index f0cdc63..2e0a98f 100644
--- a/Data/Server/server.py
+++ b/Data/Server/server.py
@@ -212,6 +212,38 @@ def _write_service_log(service: str, msg: str, scope: Optional[str] = None, *, l
         pass
 
 
+def _mask_server_value(value: str, *, prefix: int = 4, suffix: int = 4) -> str:
+    try:
+        if not value:
+            return ''
+        stripped = value.strip()
+        if len(stripped) <= prefix + suffix:
+            return '*' * len(stripped)
+        return f"{stripped[:prefix]}***{stripped[-suffix:]}"
+    except Exception:
+        return '***'
+
+
+def _summarize_socket_headers(headers) -> str:
+    try:
+        rendered = []
+        for key, value in headers.items():
+            lowered = key.lower()
+            display = value
+            if lowered == 'authorization':
+                if isinstance(value, str) and value.lower().startswith('bearer '):
+                    token = value.split(' ', 1)[1]
+                    display = f"Bearer {_mask_server_value(token)}"
+                else:
+                    display = _mask_server_value(str(value))
+            elif lowered == 'cookie':
+                display = '<redacted>'
+            rendered.append(f"{key}={display}")
+        return ", ".join(rendered)
+    except Exception:
+        return '<header-summary-unavailable>'
+
+
 # =============================================================================
 # Section: Repository Hash Tracking
 # =============================================================================
@@ -8015,6 +8047,55 @@ def screenshot_node_viewer(agent_id, node_id):
 # =============================================================================
 # Realtime channels for screenshots, macros, windows, and Ansible control.
 
+@socketio.on('connect')
+def socket_connect():
+    try:
+        sid = getattr(request, 'sid', '<unknown>')
+    except Exception:
+        sid = '<unknown>'
+    try:
+        remote_addr = request.remote_addr
+    except Exception:
+        remote_addr = None
+    try:
+        scope = _canonical_server_scope(request.headers.get(_AGENT_CONTEXT_HEADER))
+    except Exception:
+        scope = None
+    try:
+        query_pairs = [f"{k}={v}" for k, v in request.args.items()]  # type: ignore[attr-defined]
+        query_summary = "&".join(query_pairs) if query_pairs else "<none>"
+    except Exception:
+        query_summary = "<unavailable>"
+    header_summary = _summarize_socket_headers(getattr(request, 'headers', {}))
+    transport = request.args.get('transport') if hasattr(request, 'args') else None  # type: ignore[attr-defined]
+    _write_service_log(
+        'server',
+        f"socket.io connect sid={sid} ip={remote_addr} transport={transport!r} query={query_summary} headers={header_summary}",
+        scope=scope,
+    )
+
+
+@socketio.on('disconnect')
+def socket_disconnect():
+    try:
+        sid = getattr(request, 'sid', '<unknown>')
+    except Exception:
+        sid = '<unknown>'
+    try:
+        remote_addr = request.remote_addr
+    except Exception:
+        remote_addr = None
+    try:
+        scope = _canonical_server_scope(request.headers.get(_AGENT_CONTEXT_HEADER))
+    except Exception:
+        scope = None
+    _write_service_log(
+        'server',
+        f"socket.io disconnect sid={sid} ip={remote_addr}",
+        scope=scope,
+    )
+
+
 @socketio.on("agent_screenshot_task")
 def receive_screenshot_task(data):
     agent_id = data.get("agent_id")
@@ -8044,6 +8125,19 @@ def connect_agent(data):
     if not agent_id:
         return
     print(f"Agent connected: {agent_id}")
+    try:
+        scope = _normalize_service_mode((data or {}).get("service_mode"), agent_id)
+    except Exception:
+        scope = None
+    try:
+        sid = getattr(request, 'sid', '<unknown>')
+    except Exception:
+        sid = '<unknown>'
+    _write_service_log(
+        'server',
+        f"socket.io connect_agent agent_id={agent_id} sid={sid} service_mode={scope}",
+        scope=scope,
+    )
 
     # Join per-agent room so we can address this connection specifically
     try:
@@ -8051,7 +8145,7 @@ def connect_agent(data):
     except Exception:
         pass
 
-    service_mode = _normalize_service_mode((data or {}).get("service_mode"), agent_id)
+    service_mode = scope if scope else _normalize_service_mode((data or {}).get("service_mode"), agent_id)
     rec = registered_agents.setdefault(agent_id, {})
     rec["agent_id"] = agent_id
     rec["hostname"] = rec.get("hostname", "unknown")

From 45ac0dc7a4c5ee570d643d89f31119feeb5af3d5 Mon Sep 17 00:00:00 2001
From: Nicole Rappe <nicole.rappe@bunny-lab.io>
Date: Sat, 18 Oct 2025 05:31:12 -0600
Subject: [PATCH 13/14] Fix Socket.IO TLS context for pinned certificates

---
 Data/Agent/agent.py | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/Data/Agent/agent.py b/Data/Agent/agent.py
index aaaa749..1647f78 100644
--- a/Data/Agent/agent.py
+++ b/Data/Agent/agent.py
@@ -931,8 +931,15 @@ class AgentHttpClient:
             context = None
             if isinstance(verify, str) and os.path.isfile(verify):
                 try:
-                    context = ssl.create_default_context(cafile=verify)
+                    # ``create_default_context`` expects a proper CA bundle and
+                    # will reject self-signed leaf certificates that we pin on
+                    # disk. Build a dedicated client context instead and load
+                    # the pinned certificate as a trust anchor so the SYSTEM
+                    # agent can complete TLS handshakes identical to Requests.
+                    context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
                     context.check_hostname = False
+                    context.verify_mode = ssl.CERT_REQUIRED
+                    context.load_verify_locations(cafile=verify)
                     _log_agent(
                         f"SocketIO TLS alignment created SSLContext from cafile={verify}",
                         fname="agent.log",

From e2171ae4e94816b5aa68ec585e31e7d1ea1883d4 Mon Sep 17 00:00:00 2001
From: Nicole Rappe <nicole.rappe@bunny-lab.io>
Date: Sat, 18 Oct 2025 05:38:26 -0600
Subject: [PATCH 14/14] Fix Socket.IO SSL context creation

---
 Data/Agent/agent.py | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/Data/Agent/agent.py b/Data/Agent/agent.py
index 1647f78..140ae09 100644
--- a/Data/Agent/agent.py
+++ b/Data/Agent/agent.py
@@ -931,14 +931,14 @@ class AgentHttpClient:
             context = None
             if isinstance(verify, str) and os.path.isfile(verify):
                 try:
-                    # ``create_default_context`` expects a proper CA bundle and
-                    # will reject self-signed leaf certificates that we pin on
-                    # disk. Build a dedicated client context instead and load
-                    # the pinned certificate as a trust anchor so the SYSTEM
-                    # agent can complete TLS handshakes identical to Requests.
-                    context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+                    # Mirror Requests' certificate handling by starting from a
+                    # default client context (which pre-loads the system
+                    # certificate stores) and then layering the pinned
+                    # certificate bundle on top. This matches the REST client
+                    # behaviour and ensures self-signed leaf certificates work
+                    # the same way for Socket.IO handshakes.
+                    context = ssl.create_default_context()
                     context.check_hostname = False
-                    context.verify_mode = ssl.CERT_REQUIRED
                     context.load_verify_locations(cafile=verify)
                     _log_agent(
                         f"SocketIO TLS alignment created SSLContext from cafile={verify}",