From 987967549b89a4c032237f797c1efe689707ec3d Mon Sep 17 00:00:00 2001
From: Dmitry Prudnikov <mail@polaz.com>
Date: Wed, 8 Apr 2026 21:16:43 +0300
Subject: [PATCH 01/20] feat(health): detect token revocation via authenticated
 health checks
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add authenticated HEAD /api/v4/user check to periodic health monitor
probes (static token mode only; skipped in OAuth mode where no global
token is available during background checks).

Previously the health monitor stayed in `healthy` state after a token
was revoked because the unauthenticated /api/v4/version probe treated
401 as "server is alive" (status < 500). The new authenticatedTokenCheck
runs after each successful reachability probe and throws a GitLab API
401 error on revocation. classifyError maps this to 'auth', and the new
healthCheckErrorIsAuth guard in both healthy.checking.onError and
degraded.checking.onError transitions the instance directly to `failed`
state — disabling auto-reconnect until the user fixes the token.

Closes #370
---
 README.md                                 |   2 +-
 README.md.in                              |   2 +-
 src/services/HealthMonitor.ts             | 102 ++++++++++++++--
 tests/unit/services/HealthMonitor.test.ts | 140 ++++++++++++++++++++++
 4 files changed, 236 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index d8cf33cf..6b0f3656 100644
--- a/README.md
+++ b/README.md
@@ -88,7 +88,7 @@ The server handles GitLab connectivity issues gracefully:
 - **Bounded startup** — Server starts within `GITLAB_INIT_TIMEOUT_MS` (default 5s) regardless of GitLab availability
 - **Disconnected mode** — When GitLab is unreachable (`disconnected`/`failed` state), only the `manage_context` tool is exposed, with local actions such as `whoami`, `switch_profile`, and `set_scope` for diagnostics. During active reconnect (`connecting` state), the full tool list remains available so MCP clients don't lose their tool catalog during brief outages. MCP clients are notified of tool availability changes via `tools/list_changed`
 - **Auto-reconnect** — Exponential backoff reconnection (5s → 60s) with ±10% jitter
-- **Error classification** — Transient errors (network, 5xx, timeouts) trigger auto-reconnect. Auth/config errors at startup transition to `failed` state (no auto-reconnect). Runtime auth errors from tool calls are forwarded to `HealthMonitor.reportError()` via `classifyError()`; the remaining gap is token-revocation/403 detection (#370)
+- **Error classification** — Transient errors (network, 5xx, timeouts) trigger auto-reconnect. Auth/config errors at startup transition to `failed` state (no auto-reconnect). Mid-session token revocation is detected via an authenticated `HEAD /api/v4/user` check that runs alongside each periodic health check (static token mode only; skipped in OAuth mode). A 401 on this check transitions the instance to `failed` state immediately.
 - **Instance health monitor** — Each monitored instance URL has its own XState state machine. Untracked OAuth URLs currently pass through as reachable.
 
 | Variable | Default | Description |
diff --git a/README.md.in b/README.md.in
index 6b144495..8a6a1a7e 100644
--- a/README.md.in
+++ b/README.md.in
@@ -88,7 +88,7 @@ The server handles GitLab connectivity issues gracefully:
 - **Bounded startup** — Server starts within `GITLAB_INIT_TIMEOUT_MS` (default 5s) regardless of GitLab availability
 - **Disconnected mode** — When GitLab is unreachable (`disconnected`/`failed` state), only the `manage_context` tool is exposed, with local actions such as `whoami`, `switch_profile`, and `set_scope` for diagnostics. During active reconnect (`connecting` state), the full tool list remains available so MCP clients don't lose their tool catalog during brief outages. MCP clients are notified of tool availability changes via `tools/list_changed`
 - **Auto-reconnect** — Exponential backoff reconnection (5s → 60s) with ±10% jitter
-- **Error classification** — Transient errors (network, 5xx, timeouts) trigger auto-reconnect. Auth/config errors at startup transition to `failed` state (no auto-reconnect). Runtime auth errors from tool calls are forwarded to `HealthMonitor.reportError()` via `classifyError()`; the remaining gap is token-revocation/403 detection (#370)
+- **Error classification** — Transient errors (network, 5xx, timeouts) trigger auto-reconnect. Auth/config errors at startup transition to `failed` state (no auto-reconnect). Mid-session token revocation is detected via an authenticated `HEAD /api/v4/user` check that runs alongside each periodic health check (static token mode only; skipped in OAuth mode). A 401 on this check transitions the instance to `failed` state immediately.
 - **Instance health monitor** — Each monitored instance URL has its own XState state machine. Untracked OAuth URLs currently pass through as reachable.
 
 | Variable | Default | Description |
diff --git a/src/services/HealthMonitor.ts b/src/services/HealthMonitor.ts
index 30c4a4a9..1d33f162 100644
--- a/src/services/HealthMonitor.ts
+++ b/src/services/HealthMonitor.ts
@@ -35,7 +35,9 @@ import {
   HEALTH_CHECK_INTERVAL_MS,
   FAILURE_THRESHOLD,
   GITLAB_BASE_URL,
+  GITLAB_TOKEN,
 } from '../config';
+import { isOAuthEnabled } from '../oauth/index';
 
 // ============================================================================
 // Types
@@ -224,6 +226,12 @@ const performHealthCheck = fromPromise<{ degraded: boolean }, { instanceUrl: str
       throw new Error(`Health check failed for ${input.instanceUrl}`);
     }
 
+    // Detect mid-session token revocation in static token mode.
+    // Throws GitLab API 401 when the token is revoked → classifyError → 'auth'
+    // → healthCheckErrorIsAuth guard → '#connection.failed' (no auto-reconnect).
+    // No-op in OAuth mode (no global token) and when GITLAB_TOKEN is unset.
+    await authenticatedTokenCheck(input.instanceUrl, HEALTH_CHECK_PROBE_MS);
+
     const connectionManager = ConnectionManager.getInstance();
     return { degraded: isDegradedInstance(connectionManager, input.instanceUrl) };
   },
@@ -269,6 +277,55 @@ async function quickHealthCheck(
   }
 }
 
+/**
+ * Authenticated token validity check: HEAD /api/v4/user with the static token.
+ * Detects mid-session token revocation that the unauthenticated reachability check
+ * cannot see (401 from /api/v4/version is treated as "server alive").
+ *
+ * Only runs in static token mode — OAuth tokens are per-request context and are
+ * not available during background health checks.
+ *
+ * Throws a GitLab API 401 error when the token is revoked or expired.
+ * classifyError maps this to 'auth' → state machine transitions to 'failed',
+ * disabling auto-reconnect until the user intervenes.
+ *
+ * Network/timeout errors are swallowed: the unauthenticated check already verified
+ * reachability, so connectivity failures on this request are noise, not signal.
+ */
+async function authenticatedTokenCheck(instanceUrl: string, timeoutMs: number): Promise<void> {
+  // OAuth mode: token is per-request context, unavailable during background checks
+  if (isOAuthEnabled()) return;
+  // No static token configured — nothing to validate
+  if (!GITLAB_TOKEN) return;
+
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await enhancedFetch(`${instanceUrl}/api/v4/user`, {
+      method: 'HEAD',
+      signal: controller.signal,
+      retry: false,
+      rateLimit: false,
+      // skipAuth defaults to false — PRIVATE-TOKEN header injected automatically
+    });
+
+    if (response.status === 401) {
+      // Error message format matches parseGitLabApiError pattern so classifyError
+      // correctly returns 'auth' → state machine transitions to 'failed'.
+      throw new Error('GitLab API error: 401 Unauthorized - token revoked or expired');
+    }
+  } catch (error) {
+    // Re-throw the 401 auth error that signals token revocation.
+    // Swallow everything else (network/timeout) — reachability already confirmed by quickHealthCheck.
+    if (error instanceof Error && error.message.startsWith('GitLab API error: 401')) {
+      throw error;
+    }
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
 // ============================================================================
 // XState Machine Definition
 // ============================================================================
@@ -296,6 +353,11 @@ const connectionMachine = setup({
       const error = (event as { error?: unknown }).error;
       return classifyError(error) === 'transient';
     },
+    // Auth error during periodic health check → failed (no auto-reconnect)
+    healthCheckErrorIsAuth: ({ event }) => {
+      const error = (event as { error?: unknown }).error;
+      return classifyError(error) === 'auth';
+    },
   },
   actions: {
     recordSuccess: assign({
@@ -416,10 +478,22 @@ const connectionMachine = setup({
                 actions: 'recordSuccess',
               },
             ],
-            onError: {
-              target: 'idle',
-              actions: 'recordFailure',
-            },
+            onError: [
+              {
+                // Auth error (token revoked/expired) → failed immediately, no auto-reconnect
+                guard: 'healthCheckErrorIsAuth',
+                target: '#connection.failed',
+                actions: assign({
+                  lastFailureAt: () => Date.now(),
+                  lastError: ({ event }) =>
+                    event.error instanceof Error ? event.error.message : String(event.error),
+                }),
+              },
+              {
+                target: 'idle',
+                actions: 'recordFailure',
+              },
+            ],
           },
         },
       },
@@ -469,10 +543,22 @@ const connectionMachine = setup({
                 actions: 'recordSuccess',
               },
             ],
-            onError: {
-              target: 'idle',
-              actions: 'recordFailure',
-            },
+            onError: [
+              {
+                // Auth error (token revoked/expired) → failed immediately, no auto-reconnect
+                guard: 'healthCheckErrorIsAuth',
+                target: '#connection.failed',
+                actions: assign({
+                  lastFailureAt: () => Date.now(),
+                  lastError: ({ event }) =>
+                    event.error instanceof Error ? event.error.message : String(event.error),
+                }),
+              },
+              {
+                target: 'idle',
+                actions: 'recordFailure',
+              },
+            ],
           },
         },
       },
diff --git a/tests/unit/services/HealthMonitor.test.ts b/tests/unit/services/HealthMonitor.test.ts
index 2dfc897d..02792916 100644
--- a/tests/unit/services/HealthMonitor.test.ts
+++ b/tests/unit/services/HealthMonitor.test.ts
@@ -76,6 +76,14 @@ jest.mock('../../../src/config', () => ({
   HEALTH_CHECK_INTERVAL_MS: 300, // Short for testing health check substates
   FAILURE_THRESHOLD: 3,
   GITLAB_BASE_URL: 'https://gitlab.example.com',
+  // Static token present — enables authenticated health checks in tests
+  GITLAB_TOKEN: 'test-token',
+}));
+
+// Mock isOAuthEnabled — controls authenticated health check in static vs OAuth mode
+const mockIsOAuthEnabled = jest.fn();
+jest.mock('../../../src/oauth/index', () => ({
+  isOAuthEnabled: () => mockIsOAuthEnabled(),
 }));
 
 describe('HealthMonitor', () => {
@@ -90,6 +98,8 @@ describe('HealthMonitor', () => {
     mockGetCurrentInstanceUrl.mockReset();
     mockRegistryIsInitialized.mockReset();
     mockGetIntrospection.mockReset();
+    // Default: static token mode (authenticated health check enabled)
+    mockIsOAuthEnabled.mockReturnValue(false);
 
     HealthMonitor.resetInstance();
     mockInitialize.mockResolvedValue(undefined);
@@ -821,6 +831,136 @@ describe('HealthMonitor', () => {
     });
   });
 
+  describe('token revocation detection', () => {
+    it('should transition to failed when authenticated health check returns 401 (token revoked)', async () => {
+      // Regression test for #370: token revocation mid-session must move to failed state.
+      // Previously the health monitor stayed healthy because the unauthenticated
+      // /api/v4/version check treats 401 as "server alive" (status < 500).
+      mockInitialize.mockResolvedValue(undefined);
+      mockGetInstanceInfo.mockReturnValue({ version: '17.0', tier: 'premium' });
+      mockFetch.mockResolvedValue({ status: 200, ok: true });
+
+      const monitor = await initMonitor();
+      expect(monitor.getState(TEST_URL)).toBe('healthy');
+
+      // Simulate token revocation: unauthenticated check passes, authenticated fails
+      mockFetch.mockImplementation((url: string) => {
+        if (url.includes('/api/v4/user')) {
+          return Promise.resolve({ status: 401, ok: false });
+        }
+        return Promise.resolve({ status: 200, ok: true });
+      });
+
+      // Wait for health check interval (300ms) + processing
+      await new Promise((r) => setTimeout(r, 600));
+
+      // Must transition to failed — auth error, no auto-reconnect
+      expect(monitor.getState(TEST_URL)).toBe('failed');
+      expect(monitor.isInstanceReachable(TEST_URL)).toBe(false);
+    });
+
+    it('should transition from degraded to failed on token revocation', async () => {
+      // Regression test for #370 in degraded path: same auth check runs from degraded state.
+      mockInitialize.mockResolvedValue(undefined);
+      mockGetInstanceInfo.mockReturnValue({ version: 'unknown', tier: 'free' }); // degraded
+      mockFetch.mockResolvedValue({ status: 200, ok: true });
+
+      const monitor = await initMonitor();
+      expect(monitor.getState(TEST_URL)).toBe('degraded');
+
+      // Simulate token revocation
+      mockFetch.mockImplementation((url: string) => {
+        if (url.includes('/api/v4/user')) {
+          return Promise.resolve({ status: 401, ok: false });
+        }
+        return Promise.resolve({ status: 200, ok: true });
+      });
+
+      // Wait for degraded health check interval (min(300ms, 30000ms) = 300ms)
+      await new Promise((r) => setTimeout(r, 600));
+
+      expect(monitor.getState(TEST_URL)).toBe('failed');
+    });
+
+    it('should not check token validity in OAuth mode', async () => {
+      // In OAuth mode there is no global token — authenticated check must be skipped.
+      // Even if /api/v4/user returns 401, the state should remain healthy.
+      mockIsOAuthEnabled.mockReturnValue(true);
+      mockInitialize.mockResolvedValue(undefined);
+      mockGetInstanceInfo.mockReturnValue({ version: '17.0', tier: 'premium' });
+
+      mockFetch.mockImplementation((url: string) => {
+        if (url.includes('/api/v4/user')) {
+          // Would fail the connection if called — must NOT be called in OAuth mode
+          return Promise.resolve({ status: 401, ok: false });
+        }
+        return Promise.resolve({ status: 200, ok: true });
+      });
+
+      const monitor = await initMonitor();
+      expect(monitor.getState(TEST_URL)).toBe('healthy');
+
+      // Wait for health check interval
+      await new Promise((r) => setTimeout(r, 600));
+
+      // Authenticated check was skipped — connection stays healthy
+      expect(monitor.getState(TEST_URL)).toBe('healthy');
+    });
+
+    it('should swallow network errors during authenticated check', async () => {
+      // If the authenticated check throws a network error (not 401), it is swallowed.
+      // The unauthenticated check already verified reachability, so connectivity
+      // errors on the second request are noise, not signal.
+      mockInitialize.mockResolvedValue(undefined);
+      mockGetInstanceInfo.mockReturnValue({ version: '17.0', tier: 'premium' });
+      mockFetch.mockResolvedValue({ status: 200, ok: true });
+
+      const monitor = await initMonitor();
+      expect(monitor.getState(TEST_URL)).toBe('healthy');
+
+      mockFetch.mockImplementation((url: string) => {
+        if (url.includes('/api/v4/user')) {
+          return Promise.reject(new Error('network error'));
+        }
+        return Promise.resolve({ status: 200, ok: true });
+      });
+
+      await new Promise((r) => setTimeout(r, 600));
+
+      // Network error on authenticated check is swallowed — connection stays healthy
+      expect(monitor.getState(TEST_URL)).toBe('healthy');
+    });
+
+    it('should recover after token replacement via forceReconnect', async () => {
+      // After detecting token revocation (→ failed), the user can replace the token
+      // and manually reconnect via forceReconnect — must recover to healthy.
+      mockInitialize.mockResolvedValue(undefined);
+      mockGetInstanceInfo.mockReturnValue({ version: '17.0', tier: 'premium' });
+      mockFetch.mockResolvedValue({ status: 200, ok: true });
+
+      const monitor = await initMonitor();
+      expect(monitor.getState(TEST_URL)).toBe('healthy');
+
+      // Token revocation
+      mockFetch.mockImplementation((url: string) => {
+        if (url.includes('/api/v4/user')) {
+          return Promise.resolve({ status: 401, ok: false });
+        }
+        return Promise.resolve({ status: 200, ok: true });
+      });
+
+      await new Promise((r) => setTimeout(r, 600));
+      expect(monitor.getState(TEST_URL)).toBe('failed');
+
+      // User replaces token → all requests succeed again
+      mockFetch.mockResolvedValue({ status: 200, ok: true });
+      monitor.forceReconnect(TEST_URL);
+
+      await new Promise((r) => setTimeout(r, 400));
+      expect(monitor.getState(TEST_URL)).toBe('healthy');
+    });
+  });
+
   describe('periodic health checks', () => {
     it('should run health check and stay healthy when GitLab is reachable', async () => {
       mockInitialize.mockResolvedValue(undefined);

From 3ddfc41ff625dee2ad22ee6029d8cd74b68a3a38 Mon Sep 17 00:00:00 2001
From: Dmitry Prudnikov <mail@polaz.com>
Date: Wed, 8 Apr 2026 21:55:05 +0300
Subject: [PATCH 02/20] fix(health): use neutral 401 message; test no-token
 skip path
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Change authenticated check error from "token revoked or expired" to
  "token invalid" — a 401 from /api/v4/user can indicate wrong token
  value, missing scope, or other auth failure, not only revocation
- Make GITLAB_TOKEN config mock dynamic via getter
- Add test: authenticatedTokenCheck skips when GITLAB_TOKEN is unset
---
 src/services/HealthMonitor.ts             |  6 ++--
 tests/unit/services/HealthMonitor.test.ts | 37 +++++++++++++++++++++--
 2 files changed, 38 insertions(+), 5 deletions(-)

diff --git a/src/services/HealthMonitor.ts b/src/services/HealthMonitor.ts
index 1d33f162..7649d0c9 100644
--- a/src/services/HealthMonitor.ts
+++ b/src/services/HealthMonitor.ts
@@ -313,10 +313,12 @@ async function authenticatedTokenCheck(instanceUrl: string, timeoutMs: number):
     if (response.status === 401) {
       // Error message format matches parseGitLabApiError pattern so classifyError
       // correctly returns 'auth' → state machine transitions to 'failed'.
-      throw new Error('GitLab API error: 401 Unauthorized - token revoked or expired');
+      // Use "token invalid" rather than "revoked or expired" — a 401 from /api/v4/user
+      // can also indicate a wrong token value, missing scope, or other auth failure.
+      throw new Error('GitLab API error: 401 Unauthorized - token invalid');
     }
   } catch (error) {
-    // Re-throw the 401 auth error that signals token revocation.
+    // Re-throw the 401 auth error from token validation.
     // Swallow everything else (network/timeout) — reachability already confirmed by quickHealthCheck.
     if (error instanceof Error && error.message.startsWith('GitLab API error: 401')) {
       throw error;
diff --git a/tests/unit/services/HealthMonitor.test.ts b/tests/unit/services/HealthMonitor.test.ts
index 02792916..9973e5ed 100644
--- a/tests/unit/services/HealthMonitor.test.ts
+++ b/tests/unit/services/HealthMonitor.test.ts
@@ -68,7 +68,11 @@ jest.mock('../../../src/utils/fetch', () => ({
   enhancedFetch: (...args: unknown[]) => mockFetch(...args),
 }));
 
-// Mock config with shorter timeouts for testing
+// GITLAB_TOKEN mock value — controlled per-test to cover the !GITLAB_TOKEN early-return branch
+let mockGitLabToken: string | undefined = 'test-token';
+
+// Mock config with shorter timeouts for testing.
+// GITLAB_TOKEN uses a getter so individual tests can clear it (mockGitLabToken = undefined).
 jest.mock('../../../src/config', () => ({
   INIT_TIMEOUT_MS: 200,
   RECONNECT_BASE_DELAY_MS: 100,
@@ -76,8 +80,9 @@ jest.mock('../../../src/config', () => ({
   HEALTH_CHECK_INTERVAL_MS: 300, // Short for testing health check substates
   FAILURE_THRESHOLD: 3,
   GITLAB_BASE_URL: 'https://gitlab.example.com',
-  // Static token present — enables authenticated health checks in tests
-  GITLAB_TOKEN: 'test-token',
+  get GITLAB_TOKEN() {
+    return mockGitLabToken;
+  },
 }));
 
 // Mock isOAuthEnabled — controls authenticated health check in static vs OAuth mode
@@ -100,6 +105,7 @@ describe('HealthMonitor', () => {
     mockGetIntrospection.mockReset();
     // Default: static token mode (authenticated health check enabled)
     mockIsOAuthEnabled.mockReturnValue(false);
+    mockGitLabToken = 'test-token';
 
     HealthMonitor.resetInstance();
     mockInitialize.mockResolvedValue(undefined);
@@ -882,6 +888,31 @@ describe('HealthMonitor', () => {
       expect(monitor.getState(TEST_URL)).toBe('failed');
     });
 
+    it('should skip authenticated check when GITLAB_TOKEN is not configured', async () => {
+      // When GITLAB_TOKEN is absent (e.g., OAuth-only deployment without a static token),
+      // the authenticated check must be skipped — there is no token to validate.
+      mockGitLabToken = undefined;
+      mockInitialize.mockResolvedValue(undefined);
+      mockGetInstanceInfo.mockReturnValue({ version: '17.0', tier: 'premium' });
+
+      mockFetch.mockImplementation((url: string) => {
+        if (url.includes('/api/v4/user')) {
+          // Would fail the connection if called — must NOT be called without a token
+          return Promise.resolve({ status: 401, ok: false });
+        }
+        return Promise.resolve({ status: 200, ok: true });
+      });
+
+      const monitor = await initMonitor();
+      expect(monitor.getState(TEST_URL)).toBe('healthy');
+
+      // Wait for health check interval
+      await new Promise((r) => setTimeout(r, 600));
+
+      // Authenticated check was skipped — connection stays healthy
+      expect(monitor.getState(TEST_URL)).toBe('healthy');
+    });
+
     it('should not check token validity in OAuth mode', async () => {
       // In OAuth mode there is no global token — authenticated check must be skipped.
       // Even if /api/v4/user returns 401, the state should remain healthy.

From 56cd22869b9e466fbc7c72473b5635fc6a1551cb Mon Sep 17 00:00:00 2001
From: Dmitry Prudnikov <mail@polaz.com>
Date: Wed, 8 Apr 2026 22:04:05 +0300
Subject: [PATCH 03/20] test(health): extract helpers to reduce duplication in
 revocation tests

---
 tests/unit/services/HealthMonitor.test.ts | 119 ++++++----------------
 1 file changed, 32 insertions(+), 87 deletions(-)

diff --git a/tests/unit/services/HealthMonitor.test.ts b/tests/unit/services/HealthMonitor.test.ts
index 9973e5ed..f2e824dd 100644
--- a/tests/unit/services/HealthMonitor.test.ts
+++ b/tests/unit/services/HealthMonitor.test.ts
@@ -838,29 +838,34 @@ describe('HealthMonitor', () => {
   });
 
   describe('token revocation detection', () => {
-    it('should transition to failed when authenticated health check returns 401 (token revoked)', async () => {
-      // Regression test for #370: token revocation mid-session must move to failed state.
-      // Previously the health monitor stayed healthy because the unauthenticated
-      // /api/v4/version check treats 401 as "server alive" (status < 500).
+    // Buffer accounts for HEALTH_CHECK_INTERVAL_MS (300ms test config) + processing
+    const HEALTH_CYCLE_MS = 600;
+
+    /** Init monitor in healthy state with all fetch calls returning 200. */
+    async function initHealthy(): Promise<ReturnType<typeof HealthMonitor.getInstance>> {
       mockInitialize.mockResolvedValue(undefined);
       mockGetInstanceInfo.mockReturnValue({ version: '17.0', tier: 'premium' });
       mockFetch.mockResolvedValue({ status: 200, ok: true });
-
       const monitor = await initMonitor();
       expect(monitor.getState(TEST_URL)).toBe('healthy');
+      return monitor;
+    }
 
-      // Simulate token revocation: unauthenticated check passes, authenticated fails
+    /** Configure fetch to return 401 for /api/v4/user and 200 for everything else. */
+    function stubUserEndpoint401(): void {
       mockFetch.mockImplementation((url: string) => {
-        if (url.includes('/api/v4/user')) {
-          return Promise.resolve({ status: 401, ok: false });
-        }
+        if (url.includes('/api/v4/user')) return Promise.resolve({ status: 401, ok: false });
         return Promise.resolve({ status: 200, ok: true });
       });
+    }
 
-      // Wait for health check interval (300ms) + processing
-      await new Promise((r) => setTimeout(r, 600));
-
-      // Must transition to failed — auth error, no auto-reconnect
+    it('should transition to failed when authenticated health check returns 401 (token revoked)', async () => {
+      // Regression test for #370: token revocation mid-session must move to failed state.
+      // Previously the health monitor stayed healthy because the unauthenticated
+      // /api/v4/version check treats 401 as "server alive" (status < 500).
+      const monitor = await initHealthy();
+      stubUserEndpoint401();
+      await new Promise((r) => setTimeout(r, HEALTH_CYCLE_MS));
       expect(monitor.getState(TEST_URL)).toBe('failed');
       expect(monitor.isInstanceReachable(TEST_URL)).toBe(false);
     });
@@ -870,21 +875,12 @@ describe('HealthMonitor', () => {
       mockInitialize.mockResolvedValue(undefined);
       mockGetInstanceInfo.mockReturnValue({ version: 'unknown', tier: 'free' }); // degraded
       mockFetch.mockResolvedValue({ status: 200, ok: true });
-
       const monitor = await initMonitor();
       expect(monitor.getState(TEST_URL)).toBe('degraded');
 
-      // Simulate token revocation
-      mockFetch.mockImplementation((url: string) => {
-        if (url.includes('/api/v4/user')) {
-          return Promise.resolve({ status: 401, ok: false });
-        }
-        return Promise.resolve({ status: 200, ok: true });
-      });
-
-      // Wait for degraded health check interval (min(300ms, 30000ms) = 300ms)
-      await new Promise((r) => setTimeout(r, 600));
-
+      stubUserEndpoint401();
+      // degradedCheckInterval = min(HEALTH_CHECK_INTERVAL_MS, 30000) = 300ms
+      await new Promise((r) => setTimeout(r, HEALTH_CYCLE_MS));
       expect(monitor.getState(TEST_URL)).toBe('failed');
     });
 
@@ -892,49 +888,24 @@ describe('HealthMonitor', () => {
       // When GITLAB_TOKEN is absent (e.g., OAuth-only deployment without a static token),
       // the authenticated check must be skipped — there is no token to validate.
       mockGitLabToken = undefined;
+      stubUserEndpoint401(); // would fail if called — must NOT be called without a token
+      const monitor = await initMonitor();
       mockInitialize.mockResolvedValue(undefined);
       mockGetInstanceInfo.mockReturnValue({ version: '17.0', tier: 'premium' });
-
-      mockFetch.mockImplementation((url: string) => {
-        if (url.includes('/api/v4/user')) {
-          // Would fail the connection if called — must NOT be called without a token
-          return Promise.resolve({ status: 401, ok: false });
-        }
-        return Promise.resolve({ status: 200, ok: true });
-      });
-
-      const monitor = await initMonitor();
       expect(monitor.getState(TEST_URL)).toBe('healthy');
-
-      // Wait for health check interval
-      await new Promise((r) => setTimeout(r, 600));
-
-      // Authenticated check was skipped — connection stays healthy
+      await new Promise((r) => setTimeout(r, HEALTH_CYCLE_MS));
       expect(monitor.getState(TEST_URL)).toBe('healthy');
     });
 
     it('should not check token validity in OAuth mode', async () => {
       // In OAuth mode there is no global token — authenticated check must be skipped.
-      // Even if /api/v4/user returns 401, the state should remain healthy.
       mockIsOAuthEnabled.mockReturnValue(true);
+      stubUserEndpoint401(); // would fail if called — must NOT be called in OAuth mode
       mockInitialize.mockResolvedValue(undefined);
       mockGetInstanceInfo.mockReturnValue({ version: '17.0', tier: 'premium' });
-
-      mockFetch.mockImplementation((url: string) => {
-        if (url.includes('/api/v4/user')) {
-          // Would fail the connection if called — must NOT be called in OAuth mode
-          return Promise.resolve({ status: 401, ok: false });
-        }
-        return Promise.resolve({ status: 200, ok: true });
-      });
-
       const monitor = await initMonitor();
       expect(monitor.getState(TEST_URL)).toBe('healthy');
-
-      // Wait for health check interval
-      await new Promise((r) => setTimeout(r, 600));
-
-      // Authenticated check was skipped — connection stays healthy
+      await new Promise((r) => setTimeout(r, HEALTH_CYCLE_MS));
       expect(monitor.getState(TEST_URL)).toBe('healthy');
     });
 
@@ -942,51 +913,25 @@ describe('HealthMonitor', () => {
       // If the authenticated check throws a network error (not 401), it is swallowed.
       // The unauthenticated check already verified reachability, so connectivity
       // errors on the second request are noise, not signal.
-      mockInitialize.mockResolvedValue(undefined);
-      mockGetInstanceInfo.mockReturnValue({ version: '17.0', tier: 'premium' });
-      mockFetch.mockResolvedValue({ status: 200, ok: true });
-
-      const monitor = await initMonitor();
-      expect(monitor.getState(TEST_URL)).toBe('healthy');
-
+      const monitor = await initHealthy();
       mockFetch.mockImplementation((url: string) => {
-        if (url.includes('/api/v4/user')) {
-          return Promise.reject(new Error('network error'));
-        }
+        if (url.includes('/api/v4/user')) return Promise.reject(new Error('network error'));
         return Promise.resolve({ status: 200, ok: true });
       });
-
-      await new Promise((r) => setTimeout(r, 600));
-
-      // Network error on authenticated check is swallowed — connection stays healthy
+      await new Promise((r) => setTimeout(r, HEALTH_CYCLE_MS));
       expect(monitor.getState(TEST_URL)).toBe('healthy');
     });
 
     it('should recover after token replacement via forceReconnect', async () => {
       // After detecting token revocation (→ failed), the user can replace the token
       // and manually reconnect via forceReconnect — must recover to healthy.
-      mockInitialize.mockResolvedValue(undefined);
-      mockGetInstanceInfo.mockReturnValue({ version: '17.0', tier: 'premium' });
-      mockFetch.mockResolvedValue({ status: 200, ok: true });
-
-      const monitor = await initMonitor();
-      expect(monitor.getState(TEST_URL)).toBe('healthy');
-
-      // Token revocation
-      mockFetch.mockImplementation((url: string) => {
-        if (url.includes('/api/v4/user')) {
-          return Promise.resolve({ status: 401, ok: false });
-        }
-        return Promise.resolve({ status: 200, ok: true });
-      });
-
-      await new Promise((r) => setTimeout(r, 600));
+      const monitor = await initHealthy();
+      stubUserEndpoint401();
+      await new Promise((r) => setTimeout(r, HEALTH_CYCLE_MS));
       expect(monitor.getState(TEST_URL)).toBe('failed');
 
-      // User replaces token → all requests succeed again
       mockFetch.mockResolvedValue({ status: 200, ok: true });
       monitor.forceReconnect(TEST_URL);
-
       await new Promise((r) => setTimeout(r, 400));
       expect(monitor.getState(TEST_URL)).toBe('healthy');
     });

From 4cf2486b9e24d6401bcdecd7887df7cf03bdbdcf Mon Sep 17 00:00:00 2001
From: Dmitry Prudnikov <mail@polaz.com>
Date: Wed, 8 Apr 2026 22:10:21 +0300
Subject: [PATCH 04/20] test(health): reduce token revocation test duplication
 via it.each and helper cleanup

---
 tests/unit/services/HealthMonitor.test.ts | 53 ++++++++++-------------
 1 file changed, 24 insertions(+), 29 deletions(-)

diff --git a/tests/unit/services/HealthMonitor.test.ts b/tests/unit/services/HealthMonitor.test.ts
index f2e824dd..c7744772 100644
--- a/tests/unit/services/HealthMonitor.test.ts
+++ b/tests/unit/services/HealthMonitor.test.ts
@@ -841,17 +841,17 @@ describe('HealthMonitor', () => {
     // Buffer accounts for HEALTH_CHECK_INTERVAL_MS (300ms test config) + processing
     const HEALTH_CYCLE_MS = 600;
 
-    /** Init monitor in healthy state with all fetch calls returning 200. */
+    /**
+     * Init monitor in healthy state (beforeEach already provides 200 fetch + v17 instance info).
+     * Used by tests that need to start from a known-healthy baseline.
+     */
     async function initHealthy(): Promise<ReturnType<typeof HealthMonitor.getInstance>> {
-      mockInitialize.mockResolvedValue(undefined);
-      mockGetInstanceInfo.mockReturnValue({ version: '17.0', tier: 'premium' });
-      mockFetch.mockResolvedValue({ status: 200, ok: true });
       const monitor = await initMonitor();
       expect(monitor.getState(TEST_URL)).toBe('healthy');
       return monitor;
     }
 
-    /** Configure fetch to return 401 for /api/v4/user and 200 for everything else. */
+    /** Return 401 for /api/v4/user; 200 for all other URLs. */
     function stubUserEndpoint401(): void {
       mockFetch.mockImplementation((url: string) => {
         if (url.includes('/api/v4/user')) return Promise.resolve({ status: 401, ok: false });
@@ -872,9 +872,7 @@ describe('HealthMonitor', () => {
 
     it('should transition from degraded to failed on token revocation', async () => {
       // Regression test for #370 in degraded path: same auth check runs from degraded state.
-      mockInitialize.mockResolvedValue(undefined);
       mockGetInstanceInfo.mockReturnValue({ version: 'unknown', tier: 'free' }); // degraded
-      mockFetch.mockResolvedValue({ status: 200, ok: true });
       const monitor = await initMonitor();
       expect(monitor.getState(TEST_URL)).toBe('degraded');
 
@@ -884,25 +882,23 @@ describe('HealthMonitor', () => {
       expect(monitor.getState(TEST_URL)).toBe('failed');
     });
 
-    it('should skip authenticated check when GITLAB_TOKEN is not configured', async () => {
-      // When GITLAB_TOKEN is absent (e.g., OAuth-only deployment without a static token),
-      // the authenticated check must be skipped — there is no token to validate.
-      mockGitLabToken = undefined;
-      stubUserEndpoint401(); // would fail if called — must NOT be called without a token
-      const monitor = await initMonitor();
-      mockInitialize.mockResolvedValue(undefined);
-      mockGetInstanceInfo.mockReturnValue({ version: '17.0', tier: 'premium' });
-      expect(monitor.getState(TEST_URL)).toBe('healthy');
-      await new Promise((r) => setTimeout(r, HEALTH_CYCLE_MS));
-      expect(monitor.getState(TEST_URL)).toBe('healthy');
-    });
-
-    it('should not check token validity in OAuth mode', async () => {
-      // In OAuth mode there is no global token — authenticated check must be skipped.
-      mockIsOAuthEnabled.mockReturnValue(true);
-      stubUserEndpoint401(); // would fail if called — must NOT be called in OAuth mode
-      mockInitialize.mockResolvedValue(undefined);
-      mockGetInstanceInfo.mockReturnValue({ version: '17.0', tier: 'premium' });
+    it.each([
+      [
+        'no GITLAB_TOKEN',
+        (): void => {
+          mockGitLabToken = undefined;
+        },
+      ],
+      [
+        'OAuth mode',
+        (): void => {
+          mockIsOAuthEnabled.mockReturnValue(true);
+        },
+      ],
+    ])('should skip authenticated check in %s', async (_label, setup) => {
+      // Guard: /api/v4/user must never be called — if it is, the 401 would flip state to failed.
+      stubUserEndpoint401();
+      setup();
       const monitor = await initMonitor();
       expect(monitor.getState(TEST_URL)).toBe('healthy');
       await new Promise((r) => setTimeout(r, HEALTH_CYCLE_MS));
@@ -910,9 +906,8 @@ describe('HealthMonitor', () => {
     });
 
     it('should swallow network errors during authenticated check', async () => {
-      // If the authenticated check throws a network error (not 401), it is swallowed.
-      // The unauthenticated check already verified reachability, so connectivity
-      // errors on the second request are noise, not signal.
+      // Connectivity errors on the second request are noise, not signal:
+      // the unauthenticated check already verified reachability.
       const monitor = await initHealthy();
       mockFetch.mockImplementation((url: string) => {
         if (url.includes('/api/v4/user')) return Promise.reject(new Error('network error'));

From bb895f23dae7316262ed9d42f1fec67fb836efbd Mon Sep 17 00:00:00 2001
From: Dmitry Prudnikov <mail@polaz.com>
Date: Wed, 8 Apr 2026 22:13:30 +0300
Subject: [PATCH 05/20] fix(health): route 403 from authenticated probe to
 failed state; add 403 regression test

---
 src/services/HealthMonitor.ts             | 30 ++++++++++++++-------
 tests/unit/services/HealthMonitor.test.ts | 32 ++++++++++++++---------
 2 files changed, 39 insertions(+), 23 deletions(-)

diff --git a/src/services/HealthMonitor.ts b/src/services/HealthMonitor.ts
index 7649d0c9..84b00b82 100644
--- a/src/services/HealthMonitor.ts
+++ b/src/services/HealthMonitor.ts
@@ -310,17 +310,21 @@ async function authenticatedTokenCheck(instanceUrl: string, timeoutMs: number):
       // skipAuth defaults to false — PRIVATE-TOKEN header injected automatically
     });
 
-    if (response.status === 401) {
-      // Error message format matches parseGitLabApiError pattern so classifyError
-      // correctly returns 'auth' → state machine transitions to 'failed'.
-      // Use "token invalid" rather than "revoked or expired" — a 401 from /api/v4/user
-      // can also indicate a wrong token value, missing scope, or other auth failure.
-      throw new Error('GitLab API error: 401 Unauthorized - token invalid');
+    if (response.status === 401 || response.status === 403) {
+      // Both 401 (invalid/revoked token) and 403 (insufficient scope) mean the configured
+      // token cannot authenticate — include the actual status for accurate log messages.
+      throw new Error(
+        `GitLab API error: ${response.status} - token invalid or lacks required scope`,
+      );
     }
   } catch (error) {
-    // Re-throw the 401 auth error from token validation.
+    // Re-throw auth errors from the token probe (401 = invalid, 403 = insufficient scope).
     // Swallow everything else (network/timeout) — reachability already confirmed by quickHealthCheck.
-    if (error instanceof Error && error.message.startsWith('GitLab API error: 401')) {
+    if (
+      error instanceof Error &&
+      (error.message.startsWith('GitLab API error: 401') ||
+        error.message.startsWith('GitLab API error: 403'))
+    ) {
       throw error;
     }
   } finally {
@@ -355,10 +359,16 @@ const connectionMachine = setup({
       const error = (event as { error?: unknown }).error;
       return classifyError(error) === 'transient';
     },
-    // Auth error during periodic health check → failed (no auto-reconnect)
+    // Auth error during periodic health check → failed (no auto-reconnect).
+    // Checks the error message directly: classifyError maps 401 → 'auth' but 403 → 'permanent',
+    // so message-based detection handles both statuses from the authenticated probe.
     healthCheckErrorIsAuth: ({ event }) => {
       const error = (event as { error?: unknown }).error;
-      return classifyError(error) === 'auth';
+      if (!(error instanceof Error)) return false;
+      return (
+        error.message.startsWith('GitLab API error: 401') ||
+        error.message.startsWith('GitLab API error: 403')
+      );
     },
   },
   actions: {
diff --git a/tests/unit/services/HealthMonitor.test.ts b/tests/unit/services/HealthMonitor.test.ts
index c7744772..542f5e72 100644
--- a/tests/unit/services/HealthMonitor.test.ts
+++ b/tests/unit/services/HealthMonitor.test.ts
@@ -851,24 +851,30 @@ describe('HealthMonitor', () => {
       return monitor;
     }
 
-    /** Return 401 for /api/v4/user; 200 for all other URLs. */
-    function stubUserEndpoint401(): void {
+    /** Return the given status for /api/v4/user; 200 for all other URLs. */
+    function stubUserEndpointStatus(status: number): void {
       mockFetch.mockImplementation((url: string) => {
-        if (url.includes('/api/v4/user')) return Promise.resolve({ status: 401, ok: false });
+        if (url.includes('/api/v4/user')) return Promise.resolve({ status, ok: false });
         return Promise.resolve({ status: 200, ok: true });
       });
     }
 
-    it('should transition to failed when authenticated health check returns 401 (token revoked)', async () => {
-      // Regression test for #370: token revocation mid-session must move to failed state.
-      // Previously the health monitor stayed healthy because the unauthenticated
-      // /api/v4/version check treats 401 as "server alive" (status < 500).
-      const monitor = await initHealthy();
-      stubUserEndpoint401();
-      await new Promise((r) => setTimeout(r, HEALTH_CYCLE_MS));
-      expect(monitor.getState(TEST_URL)).toBe('failed');
-      expect(monitor.isInstanceReachable(TEST_URL)).toBe(false);
-    });
+    // Backward-compat alias used by several tests below
+    const stubUserEndpoint401 = (): void => stubUserEndpointStatus(401);
+
+    it.each([401, 403])(
+      'should transition to failed when authenticated health check returns %i',
+      async (authStatus) => {
+        // Regression test for #370: token auth failure mid-session must move to failed state.
+        // Previously the health monitor stayed healthy because the unauthenticated
+        // /api/v4/version check treats 401/403 as "server alive" (status < 500).
+        const monitor = await initHealthy();
+        stubUserEndpointStatus(authStatus);
+        await new Promise((r) => setTimeout(r, HEALTH_CYCLE_MS));
+        expect(monitor.getState(TEST_URL)).toBe('failed');
+        expect(monitor.isInstanceReachable(TEST_URL)).toBe(false);
+      },
+    );
 
     it('should transition from degraded to failed on token revocation', async () => {
       // Regression test for #370 in degraded path: same auth check runs from degraded state.

From e9a0ab88127323183ae09d6953d63be342879da3 Mon Sep 17 00:00:00 2001
From: Dmitry Prudnikov <mail@polaz.com>
Date: Wed, 8 Apr 2026 22:18:19 +0300
Subject: [PATCH 06/20] chore(sonar): exclude test files from copy-paste
 detection

---
 sonar-project.properties | 7 +++++++
 1 file changed, 7 insertions(+)
 create mode 100644 sonar-project.properties

diff --git a/sonar-project.properties b/sonar-project.properties
new file mode 100644
index 00000000..f0d7b632
--- /dev/null
+++ b/sonar-project.properties
@@ -0,0 +1,7 @@
+# SonarCloud configuration
+# https://sonarcloud.io/documentation/project-administration/narrowing-the-focus/
+
+# Exclude test files from Copy-Paste Detection (CPD).
+# Test files naturally repeat assertion patterns (expect, mock setup, await) across
+# test cases — this is intentional test structure, not accidental code duplication.
+sonar.cpd.exclusions=tests/**

From d7d618f730061773007ca70d6c1484a3b06a4f7c Mon Sep 17 00:00:00 2001
From: Dmitry Prudnikov <mail@polaz.com>
Date: Wed, 8 Apr 2026 22:24:44 +0300
Subject: [PATCH 07/20] refactor(health): extract shared healthCheckOnError
 constant to eliminate duplicate onError blocks

---
 src/services/HealthMonitor.ts | 49 ++++++++++++-----------------------
 1 file changed, 17 insertions(+), 32 deletions(-)

diff --git a/src/services/HealthMonitor.ts b/src/services/HealthMonitor.ts
index 84b00b82..ab4dc702 100644
--- a/src/services/HealthMonitor.ts
+++ b/src/services/HealthMonitor.ts
@@ -336,6 +336,21 @@ async function authenticatedTokenCheck(instanceUrl: string, timeoutMs: number):
 // XState Machine Definition
 // ============================================================================
 
+// Shared onError handler for health-check substates (healthy.checking, degraded.checking).
+// Auth errors (401/403 from the authenticated probe) → failed, no auto-reconnect.
+// All other errors → idle via recordFailure (transient failures accumulate toward threshold).
+const healthCheckOnError = [
+  {
+    guard: 'healthCheckErrorIsAuth' as const,
+    target: '#connection.failed' as const,
+    actions: 'recordFailure' as const,
+  },
+  {
+    target: 'idle' as const,
+    actions: 'recordFailure' as const,
+  },
+] as const;
+
 const connectionMachine = setup({
   types: {
     context: {} as MachineContext,
@@ -490,22 +505,7 @@ const connectionMachine = setup({
                 actions: 'recordSuccess',
               },
             ],
-            onError: [
-              {
-                // Auth error (token revoked/expired) → failed immediately, no auto-reconnect
-                guard: 'healthCheckErrorIsAuth',
-                target: '#connection.failed',
-                actions: assign({
-                  lastFailureAt: () => Date.now(),
-                  lastError: ({ event }) =>
-                    event.error instanceof Error ? event.error.message : String(event.error),
-                }),
-              },
-              {
-                target: 'idle',
-                actions: 'recordFailure',
-              },
-            ],
+            onError: healthCheckOnError,
           },
         },
       },
@@ -555,22 +555,7 @@ const connectionMachine = setup({
                 actions: 'recordSuccess',
               },
             ],
-            onError: [
-              {
-                // Auth error (token revoked/expired) → failed immediately, no auto-reconnect
-                guard: 'healthCheckErrorIsAuth',
-                target: '#connection.failed',
-                actions: assign({
-                  lastFailureAt: () => Date.now(),
-                  lastError: ({ event }) =>
-                    event.error instanceof Error ? event.error.message : String(event.error),
-                }),
-              },
-              {
-                target: 'idle',
-                actions: 'recordFailure',
-              },
-            ],
+            onError: healthCheckOnError,
           },
         },
       },

From e7fed88d952eb585cf4e5e281818b7c8448c8369 Mon Sep 17 00:00:00 2001
From: Dmitry Prudnikov <mail@polaz.com>
Date: Wed, 8 Apr 2026 23:43:36 +0300
Subject: [PATCH 08/20] refactor(health): replace startsWith auth checks with
 parseGitLabApiError; document 401/403 scope

---
 README.md                     |  2 +-
 README.md.in                  |  2 +-
 src/services/HealthMonitor.ts | 34 ++++++++++++++++------------------
 3 files changed, 18 insertions(+), 20 deletions(-)

diff --git a/README.md b/README.md
index 6b0f3656..85363f1f 100644
--- a/README.md
+++ b/README.md
@@ -88,7 +88,7 @@ The server handles GitLab connectivity issues gracefully:
 - **Bounded startup** — Server starts within `GITLAB_INIT_TIMEOUT_MS` (default 5s) regardless of GitLab availability
 - **Disconnected mode** — When GitLab is unreachable (`disconnected`/`failed` state), only the `manage_context` tool is exposed, with local actions such as `whoami`, `switch_profile`, and `set_scope` for diagnostics. During active reconnect (`connecting` state), the full tool list remains available so MCP clients don't lose their tool catalog during brief outages. MCP clients are notified of tool availability changes via `tools/list_changed`
 - **Auto-reconnect** — Exponential backoff reconnection (5s → 60s) with ±10% jitter
-- **Error classification** — Transient errors (network, 5xx, timeouts) trigger auto-reconnect. Auth/config errors at startup transition to `failed` state (no auto-reconnect). Mid-session token revocation is detected via an authenticated `HEAD /api/v4/user` check that runs alongside each periodic health check (static token mode only; skipped in OAuth mode). A 401 on this check transitions the instance to `failed` state immediately.
+- **Error classification** — Transient errors (network, 5xx, timeouts) trigger auto-reconnect. Auth/config errors at startup transition to `failed` state (no auto-reconnect). Mid-session token revocation is detected via an authenticated `HEAD /api/v4/user` check that runs alongside each periodic health check (static token mode only; skipped in OAuth mode). A 401 or 403 on this check transitions the instance to `failed` state immediately.
 - **Instance health monitor** — Each monitored instance URL has its own XState state machine. Untracked OAuth URLs currently pass through as reachable.
 
 | Variable | Default | Description |
diff --git a/README.md.in b/README.md.in
index 8a6a1a7e..5b8ee1bf 100644
--- a/README.md.in
+++ b/README.md.in
@@ -88,7 +88,7 @@ The server handles GitLab connectivity issues gracefully:
 - **Bounded startup** — Server starts within `GITLAB_INIT_TIMEOUT_MS` (default 5s) regardless of GitLab availability
 - **Disconnected mode** — When GitLab is unreachable (`disconnected`/`failed` state), only the `manage_context` tool is exposed, with local actions such as `whoami`, `switch_profile`, and `set_scope` for diagnostics. During active reconnect (`connecting` state), the full tool list remains available so MCP clients don't lose their tool catalog during brief outages. MCP clients are notified of tool availability changes via `tools/list_changed`
 - **Auto-reconnect** — Exponential backoff reconnection (5s → 60s) with ±10% jitter
-- **Error classification** — Transient errors (network, 5xx, timeouts) trigger auto-reconnect. Auth/config errors at startup transition to `failed` state (no auto-reconnect). Mid-session token revocation is detected via an authenticated `HEAD /api/v4/user` check that runs alongside each periodic health check (static token mode only; skipped in OAuth mode). A 401 on this check transitions the instance to `failed` state immediately.
+- **Error classification** — Transient errors (network, 5xx, timeouts) trigger auto-reconnect. Auth/config errors at startup transition to `failed` state (no auto-reconnect). Mid-session token revocation is detected via an authenticated `HEAD /api/v4/user` check that runs alongside each periodic health check (static token mode only; skipped in OAuth mode). A 401 or 403 on this check transitions the instance to `failed` state immediately.
 - **Instance health monitor** — Each monitored instance URL has its own XState state machine. Untracked OAuth URLs currently pass through as reachable.
 
 | Variable | Default | Description |
diff --git a/src/services/HealthMonitor.ts b/src/services/HealthMonitor.ts
index ab4dc702..33c7f76c 100644
--- a/src/services/HealthMonitor.ts
+++ b/src/services/HealthMonitor.ts
@@ -25,7 +25,7 @@ import {
 import { ConnectionManager } from './ConnectionManager';
 import { normalizeInstanceUrl } from '../utils/url';
 import { InstanceRegistry } from './InstanceRegistry';
-import { classifyError, type ErrorCategory } from '../utils/error-handler';
+import { classifyError, parseGitLabApiError, type ErrorCategory } from '../utils/error-handler';
 import { enhancedFetch } from '../utils/fetch';
 import { logInfo, logWarn, logError, logDebug } from '../logger';
 import {
@@ -227,8 +227,9 @@ const performHealthCheck = fromPromise<{ degraded: boolean }, { instanceUrl: str
     }
 
     // Detect mid-session token revocation in static token mode.
-    // Throws GitLab API 401 when the token is revoked → classifyError → 'auth'
-    // → healthCheckErrorIsAuth guard → '#connection.failed' (no auto-reconnect).
+    // Throws GitLab API 401/403 when the token is invalid or lacks required scope.
+    // healthCheckErrorIsAuth guard detects these by parsing the error message
+    // and routes to '#connection.failed' (no auto-reconnect).
     // No-op in OAuth mode (no global token) and when GITLAB_TOKEN is unset.
     await authenticatedTokenCheck(input.instanceUrl, HEALTH_CHECK_PROBE_MS);
 
@@ -285,9 +286,9 @@ async function quickHealthCheck(
  * Only runs in static token mode — OAuth tokens are per-request context and are
  * not available during background health checks.
  *
- * Throws a GitLab API 401 error when the token is revoked or expired.
- * classifyError maps this to 'auth' → state machine transitions to 'failed',
- * disabling auto-reconnect until the user intervenes.
+ * Throws a GitLab API 401 or 403 error when the token is invalid, revoked,
+ * expired, or lacks the required scope. The healthCheckErrorIsAuth guard detects
+ * these by parsing the status code and transitions to 'failed' (no auto-reconnect).
  *
  * Network/timeout errors are swallowed: the unauthenticated check already verified
  * reachability, so connectivity failures on this request are noise, not signal.
@@ -320,12 +321,9 @@ async function authenticatedTokenCheck(instanceUrl: string, timeoutMs: number):
   } catch (error) {
     // Re-throw auth errors from the token probe (401 = invalid, 403 = insufficient scope).
     // Swallow everything else (network/timeout) — reachability already confirmed by quickHealthCheck.
-    if (
-      error instanceof Error &&
-      (error.message.startsWith('GitLab API error: 401') ||
-        error.message.startsWith('GitLab API error: 403'))
-    ) {
-      throw error;
+    if (error instanceof Error) {
+      const parsed = parseGitLabApiError(error.message);
+      if (parsed?.status === 401 || parsed?.status === 403) throw error;
     }
   } finally {
     clearTimeout(timeoutId);
@@ -375,15 +373,15 @@ const connectionMachine = setup({
       return classifyError(error) === 'transient';
     },
     // Auth error during periodic health check → failed (no auto-reconnect).
-    // Checks the error message directly: classifyError maps 401 → 'auth' but 403 → 'permanent',
-    // so message-based detection handles both statuses from the authenticated probe.
+    // Uses parseGitLabApiError to extract the status code: both 401 (invalid token)
+    // and 403 (insufficient scope) from the authenticated probe are terminal failures.
+    // Direct message parsing is used because classifyError maps 403 → 'permanent',
+    // not 'auth', so we can't rely on classifyError for the 403 path.
     healthCheckErrorIsAuth: ({ event }) => {
       const error = (event as { error?: unknown }).error;
       if (!(error instanceof Error)) return false;
-      return (
-        error.message.startsWith('GitLab API error: 401') ||
-        error.message.startsWith('GitLab API error: 403')
-      );
+      const parsed = parseGitLabApiError(error.message);
+      return parsed?.status === 401 || parsed?.status === 403;
     },
   },
   actions: {

From b3f57c67a854cc5036bf28bd8942520a9307deaf Mon Sep 17 00:00:00 2001
From: Dmitry Prudnikov <mail@polaz.com>
Date: Wed, 8 Apr 2026 23:54:36 +0300
Subject: [PATCH 09/20] fix(health): suppress unreachable istanbul branches in
 auth probe guards

---
 src/services/HealthMonitor.ts | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/services/HealthMonitor.ts b/src/services/HealthMonitor.ts
index 33c7f76c..43605e63 100644
--- a/src/services/HealthMonitor.ts
+++ b/src/services/HealthMonitor.ts
@@ -321,6 +321,7 @@ async function authenticatedTokenCheck(instanceUrl: string, timeoutMs: number):
   } catch (error) {
     // Re-throw auth errors from the token probe (401 = invalid, 403 = insufficient scope).
     // Swallow everything else (network/timeout) — reachability already confirmed by quickHealthCheck.
+    /* istanbul ignore else */
     if (error instanceof Error) {
       const parsed = parseGitLabApiError(error.message);
       if (parsed?.status === 401 || parsed?.status === 403) throw error;
@@ -379,6 +380,7 @@ const connectionMachine = setup({
     // not 'auth', so we can't rely on classifyError for the 403 path.
     healthCheckErrorIsAuth: ({ event }) => {
       const error = (event as { error?: unknown }).error;
+      /* istanbul ignore if */
       if (!(error instanceof Error)) return false;
       const parsed = parseGitLabApiError(error.message);
       return parsed?.status === 401 || parsed?.status === 403;

From f311ab5bf11c09de1567da511de8739876b4e860 Mon Sep 17 00:00:00 2001
From: Dmitry Prudnikov <mail@polaz.com>
Date: Wed, 8 Apr 2026 23:57:00 +0300
Subject: [PATCH 10/20] fix(health): revalidate token on forceReconnect
 fast-path; add regression test

---
 src/services/HealthMonitor.ts             |  4 ++++
 tests/unit/services/HealthMonitor.test.ts | 15 +++++++++++++++
 2 files changed, 19 insertions(+)

diff --git a/src/services/HealthMonitor.ts b/src/services/HealthMonitor.ts
index 43605e63..1542422e 100644
--- a/src/services/HealthMonitor.ts
+++ b/src/services/HealthMonitor.ts
@@ -152,6 +152,10 @@ const performConnect = fromPromise<{ degraded: boolean }, { instanceUrl: string
         // classifyError maps this to 'transient' → disconnected → auto-reconnect.
         throw new Error(`Health check failed for ${input.instanceUrl}`);
       }
+      // Re-validate the token on reconnect, not just during steady-state polls.
+      // Without this, forceReconnect() while the token is still revoked would
+      // bounce failed → healthy until the next health-check interval.
+      await authenticatedTokenCheck(input.instanceUrl, HEALTH_CHECK_PROBE_MS);
       return { degraded: isDegradedInstance(connectionManager, input.instanceUrl) };
     }
 
diff --git a/tests/unit/services/HealthMonitor.test.ts b/tests/unit/services/HealthMonitor.test.ts
index 542f5e72..2516038d 100644
--- a/tests/unit/services/HealthMonitor.test.ts
+++ b/tests/unit/services/HealthMonitor.test.ts
@@ -936,6 +936,21 @@ describe('HealthMonitor', () => {
       await new Promise((r) => setTimeout(r, 400));
       expect(monitor.getState(TEST_URL)).toBe('healthy');
     });
+
+    it('should remain in failed state on forceReconnect when token is still revoked', async () => {
+      // Regression: forceReconnect uses the performConnect fast-path which must
+      // also call authenticatedTokenCheck. Without it, a still-revoked token could
+      // bounce failed → healthy until the next health-check interval.
+      const monitor = await initHealthy();
+      stubUserEndpoint401();
+      await new Promise((r) => setTimeout(r, HEALTH_CYCLE_MS));
+      expect(monitor.getState(TEST_URL)).toBe('failed');
+
+      // Token still invalid — forceReconnect must NOT recover to healthy
+      monitor.forceReconnect(TEST_URL);
+      await new Promise((r) => setTimeout(r, 400));
+      expect(monitor.getState(TEST_URL)).toBe('failed');
+    });
   });
 
   describe('periodic health checks', () => {

From 2a1bf8396889a80930fe3ab1b72f3a26a87629a9 Mon Sep 17 00:00:00 2001
From: Dmitry Prudnikov <mail@polaz.com>
Date: Thu, 9 Apr 2026 01:00:24 +0300
Subject: [PATCH 11/20] fix(health): use token-only probe to prevent session
 cookie masking

Add skipAuth: true + explicit PRIVATE-TOKEN header to the
authenticatedTokenCheck() enhancedFetch call. Without skipAuth,
loadCookieHeader() could inject a valid session cookie that
authenticates the HEAD /api/v4/user probe even after GITLAB_TOKEN
is revoked, keeping the monitor in healthy state indefinitely.

Also fixes misleading test description: the forceReconnect recovery
test scenario is not about token replacement (GITLAB_TOKEN is a
module-level constant) but about the token becoming valid again in
GitLab after a revocation event.
---
 src/services/HealthMonitor.ts             | 6 +++++-
 tests/unit/services/HealthMonitor.test.ts | 6 +++---
 2 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/src/services/HealthMonitor.ts b/src/services/HealthMonitor.ts
index 1542422e..e0271720 100644
--- a/src/services/HealthMonitor.ts
+++ b/src/services/HealthMonitor.ts
@@ -312,7 +312,11 @@ async function authenticatedTokenCheck(instanceUrl: string, timeoutMs: number):
       signal: controller.signal,
       retry: false,
       rateLimit: false,
-      // skipAuth defaults to false — PRIVATE-TOKEN header injected automatically
+      // skipAuth suppresses auto-injected credentials (session cookies, getAuthHeaders()).
+      // The explicit PRIVATE-TOKEN header ensures we validate ONLY the static token —
+      // a valid session cookie must not mask a revoked token and keep the probe alive.
+      skipAuth: true,
+      headers: { 'PRIVATE-TOKEN': GITLAB_TOKEN },
     });
 
     if (response.status === 401 || response.status === 403) {
diff --git a/tests/unit/services/HealthMonitor.test.ts b/tests/unit/services/HealthMonitor.test.ts
index 2516038d..52ef964a 100644
--- a/tests/unit/services/HealthMonitor.test.ts
+++ b/tests/unit/services/HealthMonitor.test.ts
@@ -923,9 +923,9 @@ describe('HealthMonitor', () => {
       expect(monitor.getState(TEST_URL)).toBe('healthy');
     });
 
-    it('should recover after token replacement via forceReconnect', async () => {
-      // After detecting token revocation (→ failed), the user can replace the token
-      // and manually reconnect via forceReconnect — must recover to healthy.
+    it('should recover after forceReconnect when authenticated checks succeed again', async () => {
+      // After detecting token revocation (→ failed), a manual forceReconnect should
+      // recover to healthy once the authenticated check starts succeeding again.
       const monitor = await initHealthy();
       stubUserEndpoint401();
       await new Promise((r) => setTimeout(r, HEALTH_CYCLE_MS));

From 60d9e4078fbfcd5c3b077d5036ee03931d525fb1 Mon Sep 17 00:00:00 2001
From: Dmitry Prudnikov <mail@polaz.com>
Date: Thu, 9 Apr 2026 01:03:21 +0300
Subject: [PATCH 12/20] refactor(test): move token revocation helpers to outer
 describe scope

SonarCloud flagged initHealthy and stubUserEndpointStatus as nested
functions inside describe('token revocation detection'). Moving them
to the outer describe scope satisfies the linting rule while keeping
the helpers scoped to the test suite (not exposed at module level).
---
 tests/unit/services/HealthMonitor.test.ts | 38 +++++++++++------------
 1 file changed, 19 insertions(+), 19 deletions(-)

diff --git a/tests/unit/services/HealthMonitor.test.ts b/tests/unit/services/HealthMonitor.test.ts
index 52ef964a..55a81eca 100644
--- a/tests/unit/services/HealthMonitor.test.ts
+++ b/tests/unit/services/HealthMonitor.test.ts
@@ -837,29 +837,29 @@ describe('HealthMonitor', () => {
     });
   });
 
+  /**
+   * Init monitor in healthy state (beforeEach already provides 200 fetch + v17 instance info).
+   * Used by token revocation tests that need to start from a known-healthy baseline.
+   */
+  async function initHealthy(): Promise<ReturnType<typeof HealthMonitor.getInstance>> {
+    const monitor = await initMonitor();
+    expect(monitor.getState(TEST_URL)).toBe('healthy');
+    return monitor;
+  }
+
+  /** Return the given status for /api/v4/user; 200 for all other URLs. */
+  function stubUserEndpointStatus(status: number): void {
+    mockFetch.mockImplementation((url: string) => {
+      if (url.includes('/api/v4/user')) return Promise.resolve({ status, ok: false });
+      return Promise.resolve({ status: 200, ok: true });
+    });
+  }
+
   describe('token revocation detection', () => {
     // Buffer accounts for HEALTH_CHECK_INTERVAL_MS (300ms test config) + processing
     const HEALTH_CYCLE_MS = 600;
 
-    /**
-     * Init monitor in healthy state (beforeEach already provides 200 fetch + v17 instance info).
-     * Used by tests that need to start from a known-healthy baseline.
-     */
-    async function initHealthy(): Promise<ReturnType<typeof HealthMonitor.getInstance>> {
-      const monitor = await initMonitor();
-      expect(monitor.getState(TEST_URL)).toBe('healthy');
-      return monitor;
-    }
-
-    /** Return the given status for /api/v4/user; 200 for all other URLs. */
-    function stubUserEndpointStatus(status: number): void {
-      mockFetch.mockImplementation((url: string) => {
-        if (url.includes('/api/v4/user')) return Promise.resolve({ status, ok: false });
-        return Promise.resolve({ status: 200, ok: true });
-      });
-    }
-
-    // Backward-compat alias used by several tests below
+    // Alias used by several tests below
     const stubUserEndpoint401 = (): void => stubUserEndpointStatus(401);
 
     it.each([401, 403])(

From a2a31c39e74954140258298f80f7eebddcc6a570 Mon Sep 17 00:00:00 2001
From: Dmitry Prudnikov <mail@polaz.com>
Date: Thu, 9 Apr 2026 01:45:11 +0300
Subject: [PATCH 13/20] fix(ci): bash syntax error in release summary when
 changelog has markdown links

---
 .github/workflows/release-please.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/release-please.yml b/.github/workflows/release-please.yml
index b7ea4ed1..1a8d3d50 100644
--- a/.github/workflows/release-please.yml
+++ b/.github/workflows/release-please.yml
@@ -34,7 +34,7 @@ jobs:
       release-version: ${{ steps.release.outputs.version }}
       release-tag: ${{ steps.release.outputs.tag_name }}
       release-sha: ${{ steps.release.outputs.sha }}
-      pr-number: ${{ steps.release.outputs.pr }}
+      pr-number: ${{ steps.release.outputs.pr != '' && fromJSON(steps.release.outputs.pr).number || '' }}
 
     steps:
       - name: Generate release token

From 1e3fded60f7e80ebc84da74bade8265b140009f3 Mon Sep 17 00:00:00 2001
From: Dmitry Prudnikov <mail@polaz.com>
Date: Thu, 9 Apr 2026 02:08:39 +0300
Subject: [PATCH 14/20] test(health): exercise performConnect fast-path in
 token-still-revoked regression test

---
 tests/unit/services/HealthMonitor.test.ts | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/tests/unit/services/HealthMonitor.test.ts b/tests/unit/services/HealthMonitor.test.ts
index 55a81eca..de50fec0 100644
--- a/tests/unit/services/HealthMonitor.test.ts
+++ b/tests/unit/services/HealthMonitor.test.ts
@@ -946,10 +946,16 @@ describe('HealthMonitor', () => {
       await new Promise((r) => setTimeout(r, HEALTH_CYCLE_MS));
       expect(monitor.getState(TEST_URL)).toBe('failed');
 
-      // Token still invalid — forceReconnect must NOT recover to healthy
+      // Exercise the fast-path: isConnected() = true skips full re-initialization
+      // and goes directly to quickHealthCheck + authenticatedTokenCheck.
+      // The 401 from the token probe must route to failed (not healthy) immediately.
+      const initCallsBefore = mockInitialize.mock.calls.length;
+      mockIsConnected.mockReturnValue(true);
       monitor.forceReconnect(TEST_URL);
       await new Promise((r) => setTimeout(r, 400));
       expect(monitor.getState(TEST_URL)).toBe('failed');
+      // Confirm fast-path was taken: initialize() must not have been called again
+      expect(mockInitialize.mock.calls.length).toBe(initCallsBefore);
     });
   });
 

From 8fa03111a6f89d4f0cd510e915786d93a0480cde Mon Sep 17 00:00:00 2001
From: Dmitry Prudnikov <mail@polaz.com>
Date: Thu, 9 Apr 2026 10:05:29 +0300
Subject: [PATCH 15/20] test(health): assert token-only probe contract in
 revocation tests
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add assertions that authenticatedTokenCheck() calls /api/v4/user with
skipAuth: true and explicit PRIVATE-TOKEN header across all affected
test cases (401/403 transitions, degraded→failed path, forceReconnect
fast-path). Add negative assertions in the skip-path tests (no-token,
OAuth mode) to ensure the probe URL is never fetched.

Also add GITLAB_INSTANCE_CACHE_MAX and GITLAB_INSTANCE_TTL_MS rows to
the Connection Resilience config table in README.md.

Closes #370
---
 README.md                                 |  2 ++
 tests/unit/services/HealthMonitor.test.ts | 33 +++++++++++++++++++++++
 2 files changed, 35 insertions(+)

diff --git a/README.md b/README.md
index 85363f1f..14390d36 100644
--- a/README.md
+++ b/README.md
@@ -100,6 +100,8 @@ The server handles GitLab connectivity issues gracefully:
 | `GITLAB_FAILURE_THRESHOLD` | `3` | Consecutive transient failures before disconnecting |
 | `GITLAB_TOOL_TIMEOUT_MS` | `120000` | Max time for tool/bootstrap execution before timeout |
 | `GITLAB_RESPONSE_WRITE_TIMEOUT_MS` | `10000` | Max time to flush a non-SSE response before destroying zombie connection (`0` to disable; SSE uses heartbeat) |
+| `GITLAB_INSTANCE_CACHE_MAX` | `100` | Max number of per-URL instance states kept in memory (OAuth multi-tenant; LRU eviction when exceeded) |
+| `GITLAB_INSTANCE_TTL_MS` | `3600000` | TTL for idle per-URL instance states in ms; evicted on next insert (OAuth multi-tenant) |
 
 ## Feature Flags
 
diff --git a/tests/unit/services/HealthMonitor.test.ts b/tests/unit/services/HealthMonitor.test.ts
index de50fec0..dcf6fd53 100644
--- a/tests/unit/services/HealthMonitor.test.ts
+++ b/tests/unit/services/HealthMonitor.test.ts
@@ -871,6 +871,16 @@ describe('HealthMonitor', () => {
         const monitor = await initHealthy();
         stubUserEndpointStatus(authStatus);
         await new Promise((r) => setTimeout(r, HEALTH_CYCLE_MS));
+        // Verify token-only probe contract: must use skipAuth + explicit PRIVATE-TOKEN header
+        // so ambient session cookies cannot mask a revoked static token.
+        expect(mockFetch).toHaveBeenCalledWith(
+          `${TEST_URL}/api/v4/user`,
+          expect.objectContaining({
+            method: 'HEAD',
+            skipAuth: true,
+            headers: expect.objectContaining({ 'PRIVATE-TOKEN': 'test-token' }),
+          }),
+        );
         expect(monitor.getState(TEST_URL)).toBe('failed');
         expect(monitor.isInstanceReachable(TEST_URL)).toBe(false);
       },
@@ -885,6 +895,15 @@ describe('HealthMonitor', () => {
       stubUserEndpoint401();
       // degradedCheckInterval = min(HEALTH_CHECK_INTERVAL_MS, 30000) = 300ms
       await new Promise((r) => setTimeout(r, HEALTH_CYCLE_MS));
+      // Verify token-only probe contract is enforced in the degraded path too
+      expect(mockFetch).toHaveBeenCalledWith(
+        `${TEST_URL}/api/v4/user`,
+        expect.objectContaining({
+          method: 'HEAD',
+          skipAuth: true,
+          headers: expect.objectContaining({ 'PRIVATE-TOKEN': 'test-token' }),
+        }),
+      );
       expect(monitor.getState(TEST_URL)).toBe('failed');
     });
 
@@ -909,6 +928,11 @@ describe('HealthMonitor', () => {
       expect(monitor.getState(TEST_URL)).toBe('healthy');
       await new Promise((r) => setTimeout(r, HEALTH_CYCLE_MS));
       expect(monitor.getState(TEST_URL)).toBe('healthy');
+      // Negative assertion: probe URL must not have been fetched in skip-path scenarios
+      expect(mockFetch).not.toHaveBeenCalledWith(
+        expect.stringContaining('/api/v4/user'),
+        expect.anything(),
+      );
     });
 
     it('should swallow network errors during authenticated check', async () => {
@@ -956,6 +980,15 @@ describe('HealthMonitor', () => {
       expect(monitor.getState(TEST_URL)).toBe('failed');
       // Confirm fast-path was taken: initialize() must not have been called again
       expect(mockInitialize.mock.calls.length).toBe(initCallsBefore);
+      // Verify token-only probe was invoked in the fast-path
+      expect(mockFetch).toHaveBeenCalledWith(
+        `${TEST_URL}/api/v4/user`,
+        expect.objectContaining({
+          method: 'HEAD',
+          skipAuth: true,
+          headers: expect.objectContaining({ 'PRIVATE-TOKEN': 'test-token' }),
+        }),
+      );
     });
   });
 

From a9d4bb6c58bf9c32e92e7359ffac03f759cf0690 Mon Sep 17 00:00:00 2001
From: Dmitry Prudnikov <mail@polaz.com>
Date: Thu, 9 Apr 2026 10:18:08 +0300
Subject: [PATCH 16/20] test(health): move stubUserEndpointStatus to module
 scope

Lifts stubUserEndpointStatus from inside describe('HealthMonitor') to
true module scope so SonarCloud no longer flags it as a nested function.
Replaces not.toHaveBeenCalledWith matcher with mock.calls.some() for the
skip-path negative assertion.
---
 tests/unit/services/HealthMonitor.test.ts | 25 ++++++++++++-----------
 1 file changed, 13 insertions(+), 12 deletions(-)

diff --git a/tests/unit/services/HealthMonitor.test.ts b/tests/unit/services/HealthMonitor.test.ts
index dcf6fd53..3cffb94a 100644
--- a/tests/unit/services/HealthMonitor.test.ts
+++ b/tests/unit/services/HealthMonitor.test.ts
@@ -91,6 +91,14 @@ jest.mock('../../../src/oauth/index', () => ({
   isOAuthEnabled: () => mockIsOAuthEnabled(),
 }));
 
+/** Return the given status for /api/v4/user; 200 for all other URLs. */
+function stubUserEndpointStatus(status: number): void {
+  mockFetch.mockImplementation((url: string) => {
+    if (url.includes('/api/v4/user')) return Promise.resolve({ status, ok: false });
+    return Promise.resolve({ status: 200, ok: true });
+  });
+}
+
 describe('HealthMonitor', () => {
   beforeEach(() => {
     jest.useRealTimers();
@@ -847,14 +855,6 @@ describe('HealthMonitor', () => {
     return monitor;
   }
 
-  /** Return the given status for /api/v4/user; 200 for all other URLs. */
-  function stubUserEndpointStatus(status: number): void {
-    mockFetch.mockImplementation((url: string) => {
-      if (url.includes('/api/v4/user')) return Promise.resolve({ status, ok: false });
-      return Promise.resolve({ status: 200, ok: true });
-    });
-  }
-
   describe('token revocation detection', () => {
     // Buffer accounts for HEALTH_CHECK_INTERVAL_MS (300ms test config) + processing
     const HEALTH_CYCLE_MS = 600;
@@ -929,10 +929,11 @@ describe('HealthMonitor', () => {
       await new Promise((r) => setTimeout(r, HEALTH_CYCLE_MS));
       expect(monitor.getState(TEST_URL)).toBe('healthy');
       // Negative assertion: probe URL must not have been fetched in skip-path scenarios
-      expect(mockFetch).not.toHaveBeenCalledWith(
-        expect.stringContaining('/api/v4/user'),
-        expect.anything(),
-      );
+      expect(
+        mockFetch.mock.calls.some(
+          ([url]) => typeof url === 'string' && url.includes('/api/v4/user'),
+        ),
+      ).toBe(false);
     });
 
     it('should swallow network errors during authenticated check', async () => {

From fa28b1cd5ef880f2e1d4213b48b417802df0c60d Mon Sep 17 00:00:00 2001
From: Dmitry Prudnikov <mail@polaz.com>
Date: Thu, 9 Apr 2026 10:22:04 +0300
Subject: [PATCH 17/20] docs(health): add missing JSDoc to HealthMonitor class
 and getInstance/getActorState methods

---
 src/services/HealthMonitor.ts | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/src/services/HealthMonitor.ts b/src/services/HealthMonitor.ts
index e0271720..0474e1f1 100644
--- a/src/services/HealthMonitor.ts
+++ b/src/services/HealthMonitor.ts
@@ -609,6 +609,10 @@ type StateChangeCallback = (
   to: ConnectionState,
 ) => void;
 
+/**
+ * Singleton service that manages per-instance GitLab connection health using XState state machines.
+ * Tracks connectivity state, drives automatic reconnection, and notifies listeners of state changes.
+ */
 export class HealthMonitor {
   private static instance: HealthMonitor | null = null;
   private readonly actors = new Map<string, ConnectionActor>();
@@ -618,6 +622,7 @@ export class HealthMonitor {
 
   private constructor() {}
 
+  /** Return the singleton instance, creating it on first call. */
   public static getInstance(): HealthMonitor {
     HealthMonitor.instance ??= new HealthMonitor();
     return HealthMonitor.instance;
@@ -771,6 +776,7 @@ export class HealthMonitor {
     return topLevel as ConnectionState;
   }
 
+  /** Return the current top-level state for an actor. */
   private getActorState(actor: ConnectionActor): ConnectionState {
     return this.extractState(actor.getSnapshot());
   }

From 328f95bfbd0ce5e7d9f5cd133f5e1bab76357211 Mon Sep 17 00:00:00 2001
From: Dmitry Prudnikov <mail@polaz.com>
Date: Thu, 9 Apr 2026 19:03:29 +0300
Subject: [PATCH 18/20] fix(health): narrow error swallow in
 authenticatedTokenCheck to abort and transient only

Previously all non-401/403 errors were silently swallowed, hiding programming
bugs (invalid URL, bad options) that would leave the instance in healthy state
with a broken probe. Now only AbortError (our own timeout) and classifyError
transient failures are swallowed; unexpected errors are logged and re-thrown.
---
 src/services/HealthMonitor.ts | 19 +++++++++++++++----
 1 file changed, 15 insertions(+), 4 deletions(-)

diff --git a/src/services/HealthMonitor.ts b/src/services/HealthMonitor.ts
index 0474e1f1..86ebd022 100644
--- a/src/services/HealthMonitor.ts
+++ b/src/services/HealthMonitor.ts
@@ -294,8 +294,9 @@ async function quickHealthCheck(
  * expired, or lacks the required scope. The healthCheckErrorIsAuth guard detects
  * these by parsing the status code and transitions to 'failed' (no auto-reconnect).
  *
- * Network/timeout errors are swallowed: the unauthenticated check already verified
- * reachability, so connectivity failures on this request are noise, not signal.
+ * AbortError (our own timeout) and transient connectivity failures are swallowed:
+ * reachability was already confirmed by quickHealthCheck. Unexpected errors are
+ * logged and re-thrown so programming bugs don't silently leave the instance healthy.
  */
 async function authenticatedTokenCheck(instanceUrl: string, timeoutMs: number): Promise<void> {
   // OAuth mode: token is per-request context, unavailable during background checks
@@ -328,12 +329,22 @@ async function authenticatedTokenCheck(instanceUrl: string, timeoutMs: number):
     }
   } catch (error) {
     // Re-throw auth errors from the token probe (401 = invalid, 403 = insufficient scope).
-    // Swallow everything else (network/timeout) — reachability already confirmed by quickHealthCheck.
-    /* istanbul ignore else */
     if (error instanceof Error) {
       const parsed = parseGitLabApiError(error.message);
       if (parsed?.status === 401 || parsed?.status === 403) throw error;
+
+      // Swallow our own AbortController timeout and transient connectivity failures.
+      // Reachability was already confirmed by quickHealthCheck; failures on this
+      // second request are noise, not signal.
+      if (error.name === 'AbortError' || classifyError(error) === 'transient') return;
     }
+
+    // Unexpected error (programming bug, invalid URL, etc.) — log and rethrow so it
+    // doesn't silently leave the instance healthy with a broken probe.
+    logError('Unexpected error during authenticated token health check', {
+      err: error instanceof Error ? error : new Error(String(error)),
+    });
+    throw error;
   } finally {
     clearTimeout(timeoutId);
   }

From 119cc0a38569dfedf401cfc7b15fd9b6d1e48a9e Mon Sep 17 00:00:00 2001
From: Dmitry Prudnikov <mail@polaz.com>
Date: Thu, 9 Apr 2026 19:51:28 +0300
Subject: [PATCH 19/20] test(health): derive ok flag from status code in
 stubUserEndpointStatus

ok was hardcoded to false regardless of status. Set it to
status >= 200 && status < 300 to match the real fetch contract.
---
 tests/unit/services/HealthMonitor.test.ts | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/tests/unit/services/HealthMonitor.test.ts b/tests/unit/services/HealthMonitor.test.ts
index 3cffb94a..2100840d 100644
--- a/tests/unit/services/HealthMonitor.test.ts
+++ b/tests/unit/services/HealthMonitor.test.ts
@@ -94,7 +94,8 @@ jest.mock('../../../src/oauth/index', () => ({
 /** Return the given status for /api/v4/user; 200 for all other URLs. */
 function stubUserEndpointStatus(status: number): void {
   mockFetch.mockImplementation((url: string) => {
-    if (url.includes('/api/v4/user')) return Promise.resolve({ status, ok: false });
+    if (url.includes('/api/v4/user'))
+      return Promise.resolve({ status, ok: status >= 200 && status < 300 });
     return Promise.resolve({ status: 200, ok: true });
   });
 }

From e2204b7c9560c1a95b6912d9778f641fad2dd43b Mon Sep 17 00:00:00 2001
From: Dmitry Prudnikov <mail@polaz.com>
Date: Thu, 9 Apr 2026 21:10:00 +0300
Subject: [PATCH 20/20] fix(health): throw on non-2xx responses in
 authenticatedTokenCheck

A 429 rate-limit or 5xx server error from HEAD /api/v4/user was
previously treated as a successful probe, silently masking a broken
status code. Now any non-2xx, non-auth response throws so the catch
block can classify it as transient and swallow it correctly.

Add regression tests (429/500/503) verifying the instance stays
healthy when the probe returns a transient status.
---
 src/services/HealthMonitor.ts             |  6 ++++++
 tests/unit/services/HealthMonitor.test.ts | 13 +++++++++++++
 2 files changed, 19 insertions(+)

diff --git a/src/services/HealthMonitor.ts b/src/services/HealthMonitor.ts
index 86ebd022..6974dcf6 100644
--- a/src/services/HealthMonitor.ts
+++ b/src/services/HealthMonitor.ts
@@ -327,6 +327,12 @@ async function authenticatedTokenCheck(instanceUrl: string, timeoutMs: number):
         `GitLab API error: ${response.status} - token invalid or lacks required scope`,
       );
     }
+    if (!response.ok) {
+      // Non-auth, non-2xx response (e.g. 429 rate-limit, 5xx server error) — throw so
+      // the catch block can classify it as transient and swallow appropriately, rather
+      // than letting the probe silently succeed with a broken status code.
+      throw new Error(`GitLab API error: ${response.status} - authenticated health probe failed`);
+    }
   } catch (error) {
     // Re-throw auth errors from the token probe (401 = invalid, 403 = insufficient scope).
     if (error instanceof Error) {
diff --git a/tests/unit/services/HealthMonitor.test.ts b/tests/unit/services/HealthMonitor.test.ts
index 2100840d..04047ae8 100644
--- a/tests/unit/services/HealthMonitor.test.ts
+++ b/tests/unit/services/HealthMonitor.test.ts
@@ -949,6 +949,19 @@ describe('HealthMonitor', () => {
       expect(monitor.getState(TEST_URL)).toBe('healthy');
     });
 
+    it.each([429, 500, 503])(
+      'should stay healthy when authenticated probe returns transient %i (not an auth error)',
+      async (transientStatus) => {
+        // Regression test for #370: non-auth, non-2xx responses from /api/v4/user
+        // must be classified as transient and swallowed — the instance should remain
+        // healthy because reachability was already confirmed by quickHealthCheck.
+        const monitor = await initHealthy();
+        stubUserEndpointStatus(transientStatus);
+        await new Promise((r) => setTimeout(r, HEALTH_CYCLE_MS));
+        expect(monitor.getState(TEST_URL)).toBe('healthy');
+      },
+    );
+
     it('should recover after forceReconnect when authenticated checks succeed again', async () => {
       // After detecting token revocation (→ failed), a manual forceReconnect should
       // recover to healthy once the authenticated check starts succeeding again.