From a75d939cb050aa10dfd9d6176791d90f88226212 Mon Sep 17 00:00:00 2001
From: Joey Frasier <joey.frasier@worksuite.com>
Date: Thu, 29 Jan 2026 14:36:50 -0500
Subject: [PATCH] fix(control-ui): preserve URL session parameter over
 localStorage defaults

When opening the dashboard with a ?session= URL parameter, the session
was being overwritten by applySessionDefaults() after the gateway
connected. This broke direct links to specific sessions (e.g., from
external tools like Kanban boards with per-project sessions).

The fix adds a sessionFromUrl flag that's set when a session is
explicitly provided via URL. applySessionDefaults() now checks for
this flag and skips overriding URL-provided sessions.

Fixes #4150
---
 ui/src/ui/app-gateway.ts  | 10 ++++++++++
 ui/src/ui/app-settings.ts |  2 ++
 2 files changed, 12 insertions(+)

diff --git a/ui/src/ui/app-gateway.ts b/ui/src/ui/app-gateway.ts
index ba1df61e1..18754c18e 100644
--- a/ui/src/ui/app-gateway.ts
+++ b/ui/src/ui/app-gateway.ts
@@ -84,6 +84,16 @@ function normalizeSessionKeyForDefaults(
 
 function applySessionDefaults(host: GatewayHost, defaults?: SessionDefaultsSnapshot) {
   if (!defaults?.mainSessionKey) return;
+  
+  // If session was explicitly set from URL, don't override with defaults
+  // This ensures direct links to specific sessions work correctly
+  const hostWithFlag = host as GatewayHost & { sessionFromUrl?: boolean };
+  if (hostWithFlag.sessionFromUrl) {
+    // Clear the flag after first connection so future reconnects can apply defaults if needed
+    hostWithFlag.sessionFromUrl = false;
+    return;
+  }
+  
   const resolvedSessionKey = normalizeSessionKeyForDefaults(host.sessionKey, defaults);
   const resolvedSettingsSessionKey = normalizeSessionKeyForDefaults(
     host.settings.sessionKey,
diff --git a/ui/src/ui/app-settings.ts b/ui/src/ui/app-settings.ts
index 7e3ab29cf..de31b3cb9 100644
--- a/ui/src/ui/app-settings.ts
+++ b/ui/src/ui/app-settings.ts
@@ -88,6 +88,8 @@ export function applySettingsFromUrl(host: SettingsHost) {
     const session = sessionRaw.trim();
     if (session) {
       host.sessionKey = session;
+      // Mark that this session was explicitly set from URL to prevent override by defaults
+      (host as { sessionFromUrl?: boolean }).sessionFromUrl = true;
       applySettings(host, {
         ...host.settings,
         sessionKey: session,