feat: implement telemetry system for application usage tracking

- Added telemetry utility to capture application events and metrics.
- Integrated PostHog for event tracking with distinct user identification.
- Implemented telemetry initialization, event capturing, and shutdown procedures.

feat: add UV environment setup for Python management

- Created utilities to manage Python installation and configuration.
- Implemented network optimization checks for Python installation mirrors.
- Added functions to set up managed Python environments with error handling.

feat: enhance host API communication with token management

- Introduced host API token retrieval and management for secure requests.
- Updated host API fetch functions to include token in headers.
- Added support for creating event sources with authentication.

test: add comprehensive tests for gateway protocol and startup helpers

- Implemented unit tests for gateway protocol helpers, event dispatching, and state management.
- Added tests for startup recovery strategies and process policies.
- Ensured coverage for connection monitoring and restart governance logic.

electron/gateway/state.ts

@@ -0,0 +1,57 @@
+import logManager from '@electron/service/logger';
+import type { GatewayLifecycleState } from './process-policy';
+
+export interface GatewayRuntimeStatus {
+  state: GatewayLifecycleState;
+  port: number | null;
+  pid?: number;
+  uptime?: number;
+  error?: string;
+  connectedAt?: number;
+  reconnectAttempts?: number;
+  gatewayReady?: boolean;
+}
+
+type GatewayStateHooks = {
+  emitStatus: (status: GatewayRuntimeStatus) => void;
+  onTransition?: (
+    previousState: GatewayRuntimeStatus['state'],
+    nextState: GatewayRuntimeStatus['state'],
+  ) => void;
+};
+
+export class GatewayStateController {
+  private status: GatewayRuntimeStatus = { state: 'stopped', port: null };
+
+  constructor(private readonly hooks: GatewayStateHooks) {}
+
+  getStatus(): GatewayRuntimeStatus {
+    const snapshot = { ...this.status };
+    if (snapshot.state === 'running' && snapshot.connectedAt) {
+      snapshot.uptime = Date.now() - snapshot.connectedAt;
+    }
+    return snapshot;
+  }
+
+  isConnected(isSocketOpen: boolean): boolean {
+    return this.status.state === 'running' && isSocketOpen;
+  }
+
+  setStatus(update: Partial<GatewayRuntimeStatus>): void {
+    const previousState = this.status.state;
+    this.status = { ...this.status, ...update };
+
+    if (this.status.state === 'running' && this.status.connectedAt) {
+      this.status.uptime = Date.now() - this.status.connectedAt;
+    } else if (this.status.state !== 'running') {
+      this.status.uptime = undefined;
+    }
+
+    this.hooks.emitStatus(this.status);
+
+    if (previousState !== this.status.state) {
+      logManager.debug(`Gateway state changed: ${previousState} -> ${this.status.state}`);
+      this.hooks.onTransition?.(previousState, this.status.state);
+    }
+  }
+}