@lincoln504/pi-research 0.0.0

package/src/infrastructure/state-manager.ts

@@ -0,0 +1,918 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as crypto from 'crypto';
+import * as os from 'os';
+import { logger } from '../logger.ts';
+
+/**
+ * State metrics interface
+ */
+export interface StateMetrics {
+  totalSessions: number;
+  activeSessions: number;
+  oldestSession: number | null;
+  newestSession: number | null;
+  containerUptime: number | null;
+  lastHeartbeatAge: number | null;
+}
+
+/**
+ * Session information interface
+ */
+export interface SessionInfo {
+  pid: number;
+  processStartTime?: number; // For PID reuse detection
+  lastSeen: number;
+  connectedAt: number;
+}
+
+/**
+ * Main state structure interface
+ */
+export interface SingletonState {
+  version: 1;
+  containerId: string;
+  containerName: string;
+  port: number;
+  sessions: { [sessionId: string]: SessionInfo };
+  lastUpdated: number;
+}
+
+/**
+ * Legacy session interface for backward compatibility
+ */
+export interface LegacySessionInfo {
+  lastSeen: number;
+}
+
+/**
+ * Legacy state interface for backward compatibility
+ */
+export interface LegacyState {
+  sessions: { [sessionId: string]: LegacySessionInfo };
+  containerExists: boolean;
+  containerPort: number;
+}
+
+/**
+ * Type guard to check if a value is a SingletonState
+ */
+function isSingletonState(value: unknown): value is SingletonState {
+  if (!value || typeof value !== 'object') {
+    return false;
+  }
+
+  const state = value as Partial<SingletonState>;
+
+  return (
+    state.version === 1 &&
+    typeof state.containerId === 'string' &&
+    typeof state.containerName === 'string' &&
+    typeof state.port === 'number' &&
+    typeof state.sessions === 'object' &&
+    typeof state.lastUpdated === 'number'
+  );
+}
+
+/**
+ * Type guard to check if a value is a SessionInfo
+ */
+function isSessionInfo(value: unknown): value is SessionInfo {
+  if (!value || typeof value !== 'object') {
+    return false;
+  }
+
+  const session = value as Partial<SessionInfo>;
+
+  return (
+    typeof session.pid === 'number' &&
+    typeof session.lastSeen === 'number' &&
+    typeof session.connectedAt === 'number' &&
+    (session.processStartTime === undefined || typeof session.processStartTime === 'number')
+  );
+}
+
+/**
+ * StateManager class for managing singleton state with file-based storage,
+ * file locking, backup system, and corruption recovery.
+ */
+export class StateManager {
+  // Path configuration
+  private readonly stateFilePath: string;
+  private readonly lockDirPath: string;
+  private readonly backupDirPath: string;
+  private readonly lockFilePath: string;
+
+  // Lock configuration
+  private readonly lockTimeout: number = 10000; // 10 seconds
+  private readonly lockRetries: number = 100; // 10 seconds with 100ms delay
+  private readonly lockRetryDelay: number = 100; // 100ms between retries
+  private readonly lockStaleThreshold: number = 30000; // 30 seconds
+
+  // Backup configuration
+  private readonly maxBackups: number = 5;
+
+  // Lock tracking
+  private lockHandle: fs.FileHandle | null = null;
+
+  constructor(stateDir?: string) {
+    if (!stateDir) {
+      const homeDir = os.homedir();
+      stateDir = path.join(homeDir, '.pi', 'state');
+    }
+
+    this.stateFilePath = path.join(stateDir, 'searxng-singleton.json');
+    this.lockDirPath = path.join(stateDir, '.locks');
+    this.backupDirPath = path.join(stateDir, 'backups');
+    this.lockFilePath = path.join(this.lockDirPath, 'searxng-singleton.lock');
+
+    // Clean up any stale locks on initialization (fire and forget)
+    this.cleanupStaleLocksOnStartup().catch((error: unknown) => {
+      logger.warn('[StateManager] Failed to cleanup stale locks on startup:', error instanceof Error ? error.message : String(error));
+    });
+  }
+
+  /**
+   * Clean up any stale lock files on initialization.
+   * This handles cases where locks weren't released due to crashes.
+   */
+  private async cleanupStaleLocksOnStartup(): Promise<void> {
+    await this.ensureDirectories();
+
+    try {
+      const stats = await fs.stat(this.lockFilePath);
+      const lockAge = Date.now() - stats.mtimeMs;
+
+      // Clean up locks older than stale threshold (30 seconds)
+      if (lockAge > this.lockStaleThreshold) {
+        logger.log(`[StateManager] Cleaning up stale lock file (${Math.round(lockAge / 1000)}s old)`);
+        await fs.unlink(this.lockFilePath);
+        logger.log('[StateManager] Stale lock removed');
+      }
+    } catch (error: unknown) {
+      // ENOENT is expected (no lock file exists)
+      if (error instanceof Error && 'code' in error) {
+        const errnoError = error as NodeJS.ErrnoException;
+        if (errnoError.code !== 'ENOENT') {
+          logger.warn(`[StateManager] Could not check lock file: ${errnoError.message}`);
+        }
+      }
+    }
+  }
+
+  /**
+   * Initialize directories with proper permissions
+   */
+  private async ensureDirectories(): Promise<void> {
+    const dirs = [
+      path.dirname(this.stateFilePath),
+      this.lockDirPath,
+      this.backupDirPath,
+    ];
+
+    for (const dir of dirs) {
+      try {
+        await fs.mkdir(dir, { mode: 0o700, recursive: true });
+      } catch (error: unknown) {
+        if (error instanceof Error && 'code' in error) {
+          const errnoError = error as NodeJS.ErrnoException;
+          if (errnoError.code !== 'EEXIST') {
+            throw new Error(`Failed to create directory ${dir}: ${errnoError.message}`, { cause: error });
+          }
+        } else {
+          throw new Error(`Failed to create directory ${dir}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+      }
+    }
+  }
+
+  /**
+   * Get the default state object
+   */
+  private getDefaultState(): SingletonState {
+    return {
+      version: 1,
+      containerId: '',
+      containerName: '',
+      port: 0,
+      sessions: {},
+      lastUpdated: Date.now(),
+    };
+  }
+
+  /**
+   * Read the state from the file system with lock protection
+   * @returns The current state object
+   * @throws Error if unable to read, parse, or acquire lock
+   */
+  public async readState(): Promise<SingletonState> {
+    await this.ensureDirectories();
+    return this.withLock(() => this._readState());
+  }
+
+  /**
+   * Internal read without lock acquisition (caller must hold lock)
+   */
+  private async _readState(): Promise<SingletonState> {
+    try {
+      const content = await fs.readFile(this.stateFilePath, 'utf-8');
+      const state = JSON.parse(content) as unknown;
+
+      // Validate state structure and version
+      this.validateState(state);
+
+      return state as SingletonState;
+    } catch (error: unknown) {
+      if (error instanceof Error && 'code' in error) {
+        const errnoError = error as NodeJS.ErrnoException;
+        if (errnoError.code === 'ENOENT') {
+          // File doesn't exist, return default state
+          return this.getDefaultState();
+        }
+      }
+
+      // Check for corruption
+      if (error instanceof SyntaxError || (error instanceof Error && error.message.includes('parse'))) {
+        logger.error('[StateManager] State file corrupted, attempting recovery...');
+        // Recover directly — we already hold the lock
+        await this.recoverFromCorruptionDirect();
+        // Re-read directly
+        try {
+          const recovered = await fs.readFile(this.stateFilePath, 'utf-8');
+          const recoveredState = JSON.parse(recovered) as unknown;
+          this.validateState(recoveredState);
+          return recoveredState as SingletonState;
+        } catch {
+          // Recovery produced an unreadable file — return safe default.
+          return this.getDefaultState();
+        }
+      }
+
+      throw new Error(`Failed to read state: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+  }
+
+  /**
+   * Write the state to the file system atomically with backup creation
+   * @param state The state object to write
+   * @throws Error if unable to write or backup
+   */
+  public async writeState(state: SingletonState): Promise<void> {
+    await this.ensureDirectories();
+    return this.withLock(() => this._writeState(state));
+  }
+
+  /**
+   * Internal write without lock acquisition (caller must hold lock)
+   */
+  private async _writeState(state: SingletonState): Promise<void> {
+    this.validateState(state);
+
+    // Update lastUpdated timestamp
+    state.lastUpdated = Date.now();
+
+    try {
+      // Create backup before writing
+      await this.createBackup();
+
+      // Create temporary file with UUID for atomic write
+      const tempFileName = `searxng-singleton-${crypto.randomBytes(16).toString('hex')}.tmp`;
+      const tempFilePath = path.join(path.dirname(this.stateFilePath), tempFileName);
+
+      // Write to temporary file
+      const content = JSON.stringify(state, null, 2);
+      await fs.writeFile(tempFilePath, content, 'utf-8');
+
+      // Atomic rename to target file
+      await fs.rename(tempFilePath, this.stateFilePath);
+
+      // Cleanup old backups
+      await this.cleanupOldBackups();
+    } catch (error: unknown) {
+      throw new Error(`Failed to write state: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+  }
+
+  /**
+   * Update state atomically using an updater function (read-modify-write pattern)
+   * @param updater Function that receives current state and returns updated state
+   * @throws Error if unable to read, update, or write state
+   */
+  public async updateState(updater: (state: SingletonState) => SingletonState | Promise<SingletonState>): Promise<void> {
+    await this.ensureDirectories();
+    return this.withLock(async () => {
+      const currentState = await this._readState();
+      const newState = await updater(currentState);
+      await this._writeState(newState);
+    });
+  }
+
+  /**
+   * Add a new session to the state
+   * @param sessionId The session ID to add
+   * @param param PID (number) or container name (string)
+   * @throws Error if unable to update state or read process start time
+   */
+  public async addSession(sessionId: string, param: number | string): Promise<void> {
+    let pid: number;
+    if (typeof param === 'number') {
+      pid = param;
+    } else {
+      // param is containerName string, use current process pid
+      pid = process.pid;
+    }
+
+    await this.updateState(async (state): Promise<SingletonState> => {
+      const processStartTime = await this.getProcessStartTime(pid);
+
+      state.sessions[sessionId] = {
+        pid,
+        processStartTime,
+        lastSeen: Date.now(),
+        connectedAt: Date.now(),
+      };
+
+      return state;
+    });
+  }
+
+  /**
+   * Remove a session from the state
+   * @param sessionId The session ID to remove
+   */
+  public async removeSession(sessionId: string): Promise<void> {
+    await this.updateState((state): SingletonState => {
+      if (state.sessions[sessionId] !== undefined) {
+        delete state.sessions[sessionId];
+      }
+      return state;
+    });
+  }
+
+  /**
+   * Update the heartbeat timestamp for a session
+   * @param sessionId The session ID to update
+   */
+  public async updateHeartbeat(sessionId: string): Promise<void> {
+    await this.updateState((state): SingletonState => {
+      const session = state.sessions[sessionId];
+      if (session !== undefined) {
+        session.lastSeen = Date.now();
+      }
+      return state;
+    });
+  }
+
+  /**
+   * Clean up stale sessions based on timeout and process liveness
+   * @param timeoutMs Timeout in milliseconds for session staleness
+   * @returns Number of sessions removed
+   */
+  public async cleanupStaleSessions(timeoutMs: number): Promise<number> {
+    const now = Date.now();
+    const sessionsToRemove: string[] = [];
+
+    const state = await this.readState();
+
+    for (const [sessionId, sessionInfo] of Object.entries(state.sessions)) {
+      // Primary check: lastSeen timeout
+      const lastSeenAge = now - sessionInfo.lastSeen;
+
+      if (lastSeenAge > timeoutMs) {
+        sessionsToRemove.push(sessionId);
+        continue;
+      }
+
+      // Secondary check: is process still alive?
+      const isAlive = await this.isProcessAlive(sessionInfo.pid, sessionInfo.processStartTime);
+
+      if (!isAlive) {
+        sessionsToRemove.push(sessionId);
+      }
+    }
+
+    // Remove stale sessions
+    if (sessionsToRemove.length > 0) {
+      await this.updateState((state): SingletonState => {
+        for (const sessionId of sessionsToRemove) {
+          delete state.sessions[sessionId];
+        }
+        return state;
+      });
+    }
+
+    return sessionsToRemove.length;
+  }
+
+  /**
+   * Get metrics about the current state
+   * @returns StateMetrics object with various statistics
+   */
+  public async getMetrics(): Promise<StateMetrics> {
+    const state = await this.readState();
+    const now = Date.now();
+
+    const sessionEntries = Object.entries(state.sessions);
+    const totalSessions = sessionEntries.length;
+
+    let activeSessions = 0;
+    let oldestSession: number | null = null;
+    let newestSession: number | null = null;
+    let lastHeartbeatAge: number | null = null;
+
+    for (const [, sessionInfo] of sessionEntries) {
+      // Check if session is active (lastSeen within last 5 minutes)
+      if (now - sessionInfo.lastSeen < 300000) {
+        activeSessions++;
+      }
+
+      // Track oldest and newest connection times
+      if (oldestSession === null || sessionInfo.connectedAt < oldestSession) {
+        oldestSession = sessionInfo.connectedAt;
+      }
+
+      if (newestSession === null || sessionInfo.connectedAt > newestSession) {
+        newestSession = sessionInfo.connectedAt;
+      }
+
+      // Track last heartbeat age
+      const heartbeatAge = now - sessionInfo.lastSeen;
+      if (lastHeartbeatAge === null || heartbeatAge > lastHeartbeatAge) {
+        lastHeartbeatAge = heartbeatAge;
+      }
+    }
+
+    // Calculate container uptime if container exists
+    let containerUptime: number | null = null;
+    if (state.containerId !== '') {
+      // Use lastUpdated as approximation for container uptime
+      containerUptime = now - state.lastUpdated;
+    }
+
+    return {
+      totalSessions,
+      activeSessions,
+      oldestSession,
+      newestSession,
+      containerUptime,
+      lastHeartbeatAge,
+    };
+  }
+
+  /**
+   * Check if a process is alive (optionally with start time verification)
+   * @param pid Process ID to check
+   * @param expectedStartTime Optional expected process start time (for PID reuse detection)
+   * @returns true if process is alive and matches expected start time
+   */
+  private async isProcessAlive(pid: number, expectedStartTime?: number): Promise<boolean> {
+    try {
+      // Try to send signal 0 to check if process exists
+      process.kill(pid, 0);
+
+      // If expected start time is provided, verify it matches
+      if (expectedStartTime !== undefined) {
+        const currentStartTime = await this.getProcessStartTime(pid);
+        return currentStartTime === expectedStartTime;
+      }
+
+      return true;
+    } catch {
+      // Process doesn't exist or we can't check it
+      return false;
+    }
+  }
+
+  /**
+   * Get process start time from /proc/{pid}/stat (Linux only)
+   * This is field 22 (starting after field 22, which starts after 21 spaces)
+   * @param pid Process ID
+   * @returns Process start time in jiffies (clock ticks since boot) or undefined
+   */
+  private async getProcessStartTime(pid: number): Promise<number | undefined> {
+    if (process.platform !== 'linux') {
+      return undefined;
+    }
+
+    try {
+      const statContent = await fs.readFile(`/proc/${pid}/stat`, 'utf-8');
+
+      // The stat file format is: pid (comm) state ppid pgrp session tty_nr tpgid flags minflt cminflt majflt cmajflt utime stime cutime cstime priority nice num_threads itrealvalue starttime vsize rss rsslim startcode endcode startstack kstkesp kstkeip signal blocked sigignore sigcatch wchan nswap cnswap exit_signal processor rt_priority policy delayacct_blkio_ticks guest_time cguest_time start_data end_data start_brk arg_start arg_end env_start env_end exit_code
+      // Field 22 is starttime (process start time in jiffies)
+
+      // Split by space, but need to handle the comm field which can contain spaces
+      const parts = statContent.split(' ');
+
+      // Find the closing parenthesis of the comm field
+      let commEndIndex = 0;
+      for (let i = 1; i < parts.length; i++) {
+        const part = parts[i];
+        if (part?.includes(')')) {
+          commEndIndex = i;
+          break;
+        }
+      }
+
+      // Field 22 is at index (2 + 20) = 22 (0-indexed after comm)
+      // After comm (field 1), we skip to field 22
+      const startIndex = commEndIndex + 20;
+
+      if (startIndex < parts.length) {
+        const part = parts[startIndex];
+        if (part !== undefined) {
+          const starttimeStr = part.replace(')', '');
+          const starttime = parseInt(starttimeStr, 10);
+          return isNaN(starttime) ? undefined : starttime;
+        }
+      }
+
+      return undefined;
+    } catch {
+      // Can't read process stat file
+      return undefined;
+    }
+  }
+
+  /**
+   * Create a backup of the current state file
+   * @throws Error if unable to create backup
+   */
+  private async createBackup(): Promise<void> {
+    try {
+      // Check if state file exists
+      try {
+        await fs.access(this.stateFilePath);
+      } catch {
+        // No state file to backup
+        return;
+      }
+
+      const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+      const backupFileName = `searxng-singleton-${timestamp}.json`;
+      const backupFilePath = path.join(this.backupDirPath, backupFileName);
+
+      await fs.copyFile(this.stateFilePath, backupFilePath);
+    } catch (error: unknown) {
+      throw new Error(`Failed to create backup: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+  }
+
+  /**
+   * Clean up old backups, keeping only the most recent maxBackups
+   */
+  private async cleanupOldBackups(): Promise<void> {
+    try {
+      const entries = await fs.readdir(this.backupDirPath);
+
+      if (entries.length <= this.maxBackups) {
+        return;
+      }
+
+      // Get file stats and sort by modification time (newest first)
+      const backupFiles: Array<{ name: string; mtime: Date }> = [];
+
+      for (const entry of entries) {
+        const filePath = path.join(this.backupDirPath, entry);
+        const stats = await fs.stat(filePath);
+
+        if (stats.isFile() && entry.startsWith('searxng-singleton-') && entry.endsWith('.json')) {
+          backupFiles.push({ name: entry, mtime: stats.mtime });
+        }
+      }
+
+      // Sort by mtime, newest first
+      backupFiles.sort((a, b) => b.mtime.getTime() - a.mtime.getTime());
+
+      // Remove backups beyond the max count
+      const backupsToRemove = backupFiles.slice(this.maxBackups);
+      for (const backupFile of backupsToRemove) {
+        const filePath = path.join(this.backupDirPath, backupFile.name);
+        await fs.unlink(filePath);
+      }
+    } catch (error: unknown) {
+      logger.error(`Failed to cleanup old backups: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Recover from corruption by restoring a backup or writing a default state.
+   * Does NOT call withLock — safe to call when the caller already holds the lock.
+   */
+  private async recoverFromCorruptionDirect(): Promise<void> {
+    try {
+      // Find the newest valid backup
+      let newestBackup: { name: string; mtime: Date } | null = null;
+      try {
+        const entries = await fs.readdir(this.backupDirPath);
+        for (const entry of entries) {
+          const filePath = path.join(this.backupDirPath, entry);
+          const stats = await fs.stat(filePath);
+          if (stats.isFile() && entry.startsWith('searxng-singleton-') && entry.endsWith('.json')) {
+            if (newestBackup === null || stats.mtime > newestBackup.mtime) {
+              newestBackup = { name: entry, mtime: stats.mtime };
+            }
+          }
+        }
+      } catch {
+        // Backup directory unreadable — fall through to default state
+      }
+
+      if (newestBackup !== null) {
+        const backupPath = path.join(this.backupDirPath, newestBackup.name);
+        await fs.copyFile(backupPath, this.stateFilePath);
+        logger.log(`[StateManager] Recovered state from backup: ${newestBackup.name}`);
+      } else {
+        // No backups — write default state directly (atomic rename, no lock needed)
+        const defaultState = this.getDefaultState();
+        defaultState.lastUpdated = Date.now();
+        const tempFile = `searxng-singleton-${crypto.randomBytes(16).toString('hex')}.tmp`;
+        const tempPath = path.join(path.dirname(this.stateFilePath), tempFile);
+        await fs.writeFile(tempPath, JSON.stringify(defaultState, null, 2), 'utf-8');
+        await fs.rename(tempPath, this.stateFilePath);
+        logger.log('[StateManager] Recovered with default state (no backups available)');
+      }
+    } catch (error: unknown) {
+      const message = error instanceof Error ? error.message : String(error);
+      logger.error(`[StateManager] Failed to recover from corruption: ${message}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Acquire a filesystem lock for exclusive access to state
+   * @throws Error if unable to acquire lock within timeout
+   */
+  private async acquireLock(): Promise<void> {
+    await this.ensureDirectories();
+
+    const startTime = Date.now();
+
+    for (let _attempt = 0; _attempt < this.lockRetries; _attempt++) {
+      try {
+        this.lockHandle = await fs.open(this.lockFilePath, 'wx');
+        return;
+      } catch (error: unknown) {
+        if (error instanceof Error && 'code' in error) {
+          const errnoError = error as NodeJS.ErrnoException;
+          if (errnoError.code === 'EEXIST') {
+            // Check if lock is stale
+            try {
+              const stats = await fs.stat(this.lockFilePath);
+              const lockAge = Date.now() - stats.mtimeMs;
+
+              if (lockAge > this.lockStaleThreshold) {
+                // Stale lock, remove it
+                await fs.unlink(this.lockFilePath);
+                continue;
+              }
+            } catch {
+              // Can't stat lock file, continue waiting
+            }
+
+            // Wait before retrying
+            if (Date.now() - startTime < this.lockTimeout) {
+              await this.sleep(this.lockRetryDelay);
+              continue;
+            }
+
+          }
+        }
+        throw error;
+      }
+    }
+
+    throw new Error(`Failed to acquire lock after ${this.lockRetries} retries`);
+  }
+
+  /**
+   * Release the filesystem lock
+   * @throws Error if unable to release lock
+   */
+  private async releaseLock(): Promise<void> {
+    if (this.lockHandle !== null) {
+      try {
+        await this.lockHandle.close();
+        this.lockHandle = null;
+      } catch (error: unknown) {
+        throw new Error(`Failed to close lock file handle: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+      }
+    }
+
+    try {
+      await fs.unlink(this.lockFilePath);
+    } catch (error: unknown) {
+      if (error instanceof Error && 'code' in error) {
+        const errnoError = error as NodeJS.ErrnoException;
+        if (errnoError.code !== 'ENOENT') {
+          throw new Error(`Failed to remove lock file: ${errnoError.message}`, { cause: error });
+        }
+      }
+    }
+  }
+
+  /**
+   * Execute a callback function while holding the lock with timeout.
+   * @param callback Async function to execute while holding the lock
+   * @param timeout Maximum time to hold the lock (default 30 seconds)
+   * @returns The return value of the callback
+   * @throws Error if unable to acquire lock, timeout, or callback throws
+   */
+  private async withLock<T>(
+    callback: () => Promise<T> | T,
+    timeout: number = 30000,
+  ): Promise<T> {
+    let lockAcquired = false;
+    let lockAcquisitionTimeoutHandle: NodeJS.Timeout | null = null;
+    let callbackTimeoutHandle: NodeJS.Timeout | null = null;
+
+    try {
+      // Acquire lock with timeout
+      await Promise.race([
+        this.acquireLock(),
+        new Promise<never>((_resolve, reject) => {
+          lockAcquisitionTimeoutHandle = setTimeout(() => {
+            reject(new Error(`Lock acquisition timed out after ${timeout}ms`));
+          }, timeout);
+        }),
+      ]);
+      lockAcquired = true;
+
+      // Clear lock acquisition timeout since we acquired the lock
+      if (lockAcquisitionTimeoutHandle) {
+        clearTimeout(lockAcquisitionTimeoutHandle);
+        lockAcquisitionTimeoutHandle = null;
+      }
+
+      // Execute callback with timeout
+      return await Promise.race([
+        callback(),
+        new Promise<never>((_resolve, reject) => {
+          callbackTimeoutHandle = setTimeout(() => {
+            reject(new Error(`Lock operation timed out after ${timeout}ms`));
+          }, timeout);
+        }),
+      ]);
+    } finally {
+      // Clear any remaining timeout handles
+      if (lockAcquisitionTimeoutHandle) {
+        clearTimeout(lockAcquisitionTimeoutHandle);
+      }
+      if (callbackTimeoutHandle) {
+        clearTimeout(callbackTimeoutHandle);
+      }
+
+      if (lockAcquired) {
+        try {
+          await this.releaseLock();
+        } catch (error: unknown) {
+          logger.error('[StateManager] Failed to release lock:', error);
+        }
+      }
+    }
+  }
+
+  /**
+   * Validate the structure and version of a state object
+   * @param state The state object to validate
+   * @throws Error if state structure or version is invalid
+   */
+  private validateState(state: unknown): void {
+    if (!state || typeof state !== 'object') {
+      throw new Error('Invalid state: not an object');
+    }
+
+    if (!isSingletonState(state)) {
+      throw new Error('Invalid state: structure or version mismatch');
+    }
+
+    // Type guard already validated the structure, now validate values
+    if (state.port < 0 || state.port > 65535) {
+      throw new Error(`Invalid state: port must be a number between 0 and 65535, got ${state.port}`);
+    }
+
+    if (state.lastUpdated < 0) {
+      throw new Error(`Invalid state: lastUpdated must be a non-negative number, got ${state.lastUpdated}`);
+    }
+
+    for (const [sessionId, sessionData] of Object.entries(state.sessions)) {
+      if (typeof sessionId !== 'string') {
+        throw new Error('Invalid state: session IDs must be strings');
+      }
+
+      if (!isSessionInfo(sessionData)) {
+        throw new Error(`Invalid state: session data for ${sessionId} has invalid structure`);
+      }
+
+      if (sessionData.pid < 0) {
+        throw new Error(`Invalid state: pid for ${sessionId} must be a non-negative number, got ${sessionData.pid}`);
+      }
+
+      if (sessionData.processStartTime !== undefined && sessionData.processStartTime < 0) {
+        throw new Error(`Invalid state: processStartTime for ${sessionId} must be a non-negative number or undefined, got ${sessionData.processStartTime}`);
+      }
+
+      if (sessionData.lastSeen < 0) {
+        throw new Error(`Invalid state: lastSeen for ${sessionId} must be a non-negative number, got ${sessionData.lastSeen}`);
+      }
+
+      if (sessionData.connectedAt < 0) {
+        throw new Error(`Invalid state: connectedAt for ${sessionId} must be a non-negative number, got ${sessionData.connectedAt}`);
+      }
+    }
+  }
+
+  /**
+   * Sleep for a specified number of milliseconds
+   * @param ms The number of milliseconds to sleep
+   */
+  private sleep(ms: number): Promise<void> {
+    return new Promise<void>((resolve) => setTimeout(resolve, ms));
+  }
+
+
+  // ==================== Backward compatibility methods ====================
+
+  /**
+   * Get a session by ID (backward compatible)
+   * @param sessionId The session ID to retrieve
+   * @returns The session data or null if not found
+   */
+  public async getSession(sessionId: string): Promise<LegacySessionInfo | null> {
+    const state = await this.readState();
+    const session = state.sessions[sessionId];
+
+    if (session === undefined) {
+      return null;
+    }
+
+    // Return only lastSeen for backward compatibility
+    return {
+      lastSeen: session.lastSeen,
+    };
+  }
+
+  /**
+   * Update the activity timestamp for a session (backward compatible)
+   * @param sessionId The session ID to update
+   */
+  public async updateActivity(sessionId: string): Promise<void> {
+    await this.updateHeartbeat(sessionId);
+  }
+
+  /**
+   * Get all sessions (backward compatible)
+   * @returns A copy of all sessions with legacy structure
+   */
+  public async getAllSessions(): Promise<{ [sessionId: string]: LegacySessionInfo }> {
+    const state = await this.readState();
+    const legacySessions: { [sessionId: string]: LegacySessionInfo } = {};
+
+    for (const [sessionId, sessionInfo] of Object.entries(state.sessions)) {
+      legacySessions[sessionId] = {
+        lastSeen: sessionInfo.lastSeen,
+      };
+    }
+
+    return legacySessions;
+  }
+
+  /**
+   * Clean up resources (release lock if held)
+   * Should be called when shutting down
+   */
+  public async cleanup(): Promise<void> {
+    if (this.lockHandle !== null) {
+      try {
+        await this.releaseLock();
+      } catch (error: unknown) {
+        logger.error('Failed to release lock during cleanup:', error);
+      }
+    }
+  }
+
+  // ==================== Public getter methods ====================
+
+  /**
+   * Get the state file path
+   * @returns The path to the state file
+   */
+  public getStateFilePath(): string {
+    return this.stateFilePath;
+  }
+
+  /**
+   * Get the lock file path
+   * @returns The path to the lock file
+   */
+  public getLockFilePath(): string {
+    return this.lockFilePath;
+  }
+
+  /**
+   * Get the backup directory path
+   * @returns The path to the backup directory
+   */
+  public getBackupDirPath(): string {
+    return this.backupDirPath;
+  }
+}