@northflare/runner 0.0.1

package/src/runner-sse.ts

@@ -0,0 +1,847 @@
+/**
+ * Main RunnerApp class - entry point and lifecycle manager for the runner app
+ * Updated to use SSE for real-time messaging instead of ElectricSQL
+ */
+
+import {
+  RunnerConfig,
+  ConversationContext,
+  JsonRpcMessage,
+  RetryStrategy,
+  RunnerRepo,
+} from "./types";
+import { IRunnerApp } from "./types/runner-interface";
+import { MessageHandler } from "./components/message-handler-sse";
+import { ClaudeManager } from "./components/claude-sdk-manager";
+import { EnhancedRepositoryManager } from "./components/enhanced-repository-manager";
+import { StateManager } from "./utils/StateManager";
+import { createLogger } from "./utils/logger";
+import { statusLineManager } from "./utils/status-line";
+import fs from "fs/promises";
+import path from "path";
+import computerName from "computer-name";
+
+const logger = createLogger("RunnerApp");
+
+export class RunnerApp implements IRunnerApp {
+  private messageHandler!: MessageHandler;
+  private claudeManager!: ClaudeManager;
+  private repositoryManager!: EnhancedRepositoryManager;
+  private stateManager!: StateManager;
+  private agentConversations: Map<string, ConversationContext>; // Keyed by conversation.id
+  private config: RunnerConfig;
+  private configPath?: string;
+  private heartbeatInterval?: NodeJS.Timeout;
+  private isRunning: boolean = false;
+  private isRegistered: boolean = false;
+  private delayFn: (ms: number) => Promise<void> = (ms) =>
+    new Promise((resolve) => setTimeout(resolve, ms));
+
+  // UID ownership fields
+  private runnerUid: string | null = null;
+  private lastProcessedAt: Date | null = null;
+  private isActiveRunner: boolean = false;
+
+  // Track conversations started before takeover
+  private preHandoffConversations = new Set<string>();
+
+  constructor(config: RunnerConfig, configPath?: string) {
+    this.config = config;
+    this.configPath = configPath;
+    this.agentConversations = new Map();
+    // Note: State manager will be initialized in start() after fetching runnerId
+  }
+
+  private async fetchRunnerId(): Promise<string> {
+    const token = process.env["NORTHFLARE_RUNNER_TOKEN"];
+    if (!token) {
+      throw new Error("NORTHFLARE_RUNNER_TOKEN environment variable is required");
+    }
+
+    try {
+      const response = await fetch(`${this.config.orchestratorUrl}/api/runner/id`, {
+        method: "GET",
+        headers: {
+          Authorization: `Bearer ${token}`,
+        },
+      });
+
+      if (!response.ok) {
+        const error = await response.json().catch(() => ({ error: response.statusText })) as any;
+        throw new Error(`Failed to fetch runner ID: ${error.error || response.statusText}`);
+      }
+
+      const data = await response.json() as { runnerId?: string };
+      if (!data.runnerId) {
+        throw new Error("Server did not return runnerId");
+      }
+
+      logger.info(`Fetched runnerId: ${data.runnerId}`);
+      return data.runnerId;
+    } catch (error) {
+      logger.error("Failed to fetch runner ID from orchestrator", error);
+      throw error;
+    }
+  }
+
+  private initializeComponents(): void {
+    // Initialize repository manager first as it's used by Claude manager
+    this.repositoryManager = new EnhancedRepositoryManager(this);
+
+    // Initialize Claude manager with repository manager (using SDK-native manager)
+    this.claudeManager = new ClaudeManager(this, this.repositoryManager);
+
+    // Initialize message handler with SSE support
+    this.messageHandler = new MessageHandler(this);
+  }
+
+  async start(): Promise<void> {
+    if (this.isRunning) {
+      throw new Error("Runner is already running");
+    }
+
+    try {
+      // Fetch runnerId from orchestrator using token
+      const runnerId = await this.fetchRunnerId();
+      this.config.runnerId = runnerId;
+
+      // Initialize state manager with runnerId
+      this.stateManager = new StateManager(this.config.dataDir, runnerId);
+
+      // Initialize other components
+      this.initializeComponents();
+
+      // Load persisted state
+      const savedState = await this.stateManager.loadState();
+      if (savedState) {
+        // Restore state from previous run
+        this.config.runnerId = savedState.runnerId;
+        this.runnerUid = savedState.runnerUid;
+        this.lastProcessedAt = savedState.lastProcessedAt
+          ? new Date(savedState.lastProcessedAt)
+          : null;
+        this.isActiveRunner = savedState.isActiveRunner;
+
+        logger.info("Restored runner state from disk", {
+          runnerId: savedState.runnerId,
+          runnerUid: savedState.runnerUid,
+          lastProcessedAt: savedState.lastProcessedAt,
+          isActiveRunner: savedState.isActiveRunner,
+        });
+
+        // Load runnerRepos for this specific runnerId
+        if (this.configPath && savedState.runnerId) {
+          await this.loadRunnerReposForId(savedState.runnerId);
+        }
+      }
+
+      // Register with retry strategy
+      await this.registerWithRetry();
+
+      // Log debug info after registration
+      if (process.env["DEBUG"] === "true") {
+        logger.debug("Runner initialized with ownership details", {
+          runnerId: this.config.runnerId,
+          runnerUid: this.runnerUid,
+          lastProcessedAt: this.lastProcessedAt?.toISOString() || "null",
+          isActiveRunner: this.isActiveRunner,
+          orchestratorUrl: this.config.orchestratorUrl,
+        });
+      }
+
+      // Start message processing with SSE
+      await this.messageHandler.startProcessing();
+
+      // Start heartbeat after successful registration
+      this.startHeartbeat();
+
+      this.isRunning = true;
+
+      logger.info(`Runner ${this.config.runnerId} started successfully`);
+    } catch (error) {
+      logger.error("Failed to start runner:", error);
+      throw error;
+    }
+  }
+
+  async stop(): Promise<void> {
+    if (!this.isRunning) {
+      return;
+    }
+
+    logger.info(`Stopping runner ${this.config.runnerId}...`);
+
+    // Stop heartbeat
+    if (this.heartbeatInterval) {
+      clearInterval(this.heartbeatInterval);
+      this.heartbeatInterval = undefined;
+    }
+
+    // Stop all conversations
+    await this.stopAllConversations();
+
+    // Stop message processing
+    await this.messageHandler.stopProcessing();
+
+    // Clean up status line
+    statusLineManager.dispose();
+
+    this.isRunning = false;
+
+    logger.info(`Runner ${this.config.runnerId} stopped`);
+  }
+
+  async notify(method: string, params: any): Promise<void> {
+    try {
+      // Log RPC notification in debug mode
+      logger.debug(`[RPC] Sending notification: ${method}`, {
+        method,
+        params: JSON.stringify(params, null, 2),
+      });
+
+      // Send notification with retry logic
+      await this.sendToOrchestratorWithRetry({
+        jsonrpc: "2.0",
+        method,
+        params,
+      });
+    } catch (error) {
+      // Special handling for heartbeat errors - just log a simple line
+      if (method === "runner.heartbeat") {
+        const errorMessage =
+          error instanceof Error ? error.message : String(error);
+        logger.error(`Heartbeat failed: ${errorMessage}`);
+      } else {
+        // For other RPC errors, log the method and error without stack
+        const errorMessage =
+          error instanceof Error ? error.message : String(error);
+        logger.error(
+          `RPC Error: Failed to notify with method '${method}': ${errorMessage}`
+        );
+      }
+      throw error;
+    }
+  }
+
+  async sendToOrchestrator(message: JsonRpcMessage): Promise<any> {
+    try {
+      // Log RPC request in debug mode
+      logger.debug(`[RPC] Sending request:`, {
+        method: message.method,
+        id: message.id,
+        params: message.params
+          ? JSON.stringify(message.params, null, 2)
+          : undefined,
+      });
+
+      // Build headers - only include X-Runner-Id if we have one (not during registration)
+      const headers: Record<string, string> = {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${process.env["NORTHFLARE_RUNNER_TOKEN"]}`,
+      };
+
+      // Only add X-Runner-Id if we're registered (not during registration)
+      if (this.config.runnerId && message.method !== "runner.register") {
+        headers["X-Runner-Id"] = this.config.runnerId;
+      }
+
+      const response = await fetch(
+        `${this.config.orchestratorUrl}/api/runner/messages`,
+        {
+          method: "POST",
+          headers,
+          body: JSON.stringify(message),
+          signal: AbortSignal.timeout(30000), // 30 second timeout
+        }
+      );
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`HTTP ${response.status}: ${errorText}`);
+      }
+
+      const result = (await response.json()) as any;
+
+      // Log RPC response in debug mode
+      logger.debug(`[RPC] Received response:`, {
+        method: message.method,
+        id: message.id,
+        result: result?.result
+          ? JSON.stringify(result.result, null, 2)
+          : undefined,
+        error: result?.error
+          ? JSON.stringify(result.error, null, 2)
+          : undefined,
+      });
+
+      return result;
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+
+      // Don't log verbose errors for heartbeat failures
+      if (message.method === "runner.heartbeat") {
+        // Heartbeat errors are already logged in notify()
+      } else if (message.method === "runner.register") {
+        // Special case for registration failures
+        logger.error(`Registration failed: ${errorMessage}`);
+      } else {
+        // For other RPC messages, log the attempted message and error
+        logger.error(`RPC failed:`, {
+          method: message.method,
+          params: message.params,
+          error: errorMessage,
+        });
+      }
+      throw error;
+    }
+  }
+
+  getConversationContext(
+    conversationId: string
+  ): ConversationContext | undefined {
+    // Using conversation.id as primary key for conversation tracking
+    const context = this.agentConversations.get(conversationId);
+    console.log(`[Runner] getConversationContext lookup:`, {
+      conversationId,
+      found: !!context,
+      totalConversations: this.agentConversations.size,
+      allConversationIds: Array.from(this.agentConversations.keys()),
+    });
+    return context;
+  }
+
+  private async registerRunner(): Promise<void> {
+    try {
+      // Filter runnerRepos by valid paths
+      let filteredRunnerRepos: RunnerRepo[] = [];
+
+      if (this.config.runnerRepos && Array.isArray(this.config.runnerRepos)) {
+        for (const repo of this.config.runnerRepos) {
+          try {
+            const resolvedPath = path.resolve(repo.path);
+            const stats = await fs.stat(resolvedPath);
+            if (stats.isDirectory()) {
+              filteredRunnerRepos.push(repo);
+              logger.info(
+                `RunnerRepo validated: ${repo.name} at ${resolvedPath}`
+              );
+            } else {
+              logger.error(
+                `RunnerRepo path is not a directory: ${repo.name} at ${resolvedPath}`
+              );
+            }
+          } catch (error) {
+            logger.error(
+              `RunnerRepo path does not exist: ${repo.name} at ${repo.path}`
+            );
+          }
+        }
+      }
+
+      // Get computer name for registration
+      let hostComputerName: string | undefined;
+      try {
+        hostComputerName = await computerName();
+      } catch (error) {
+        logger.warn("Failed to get computer name, will use default", error);
+      }
+
+      const response = await this.sendToOrchestratorWithRetry({
+        jsonrpc: "2.0",
+        id: "register-" + Date.now(),
+        method: "runner.register",
+        params: {
+          version: "1.0.0",
+          runnerRepos: filteredRunnerRepos,
+          computerName: hostComputerName,
+        },
+      });
+
+      // Debug log the full response
+      logger.info(`Registration response:`, JSON.stringify(response, null, 2));
+
+      // Log the runnerRepos being sent and received
+      if (process.env["DEBUG"] === "true") {
+        logger.debug(
+          "Registration runnerRepos sent:",
+          JSON.stringify(filteredRunnerRepos)
+        );
+        logger.debug(
+          "Registration runnerRepos received:",
+          JSON.stringify(response?.result?.runnerRepos)
+        );
+      }
+
+      // Check for JSONRPC error response
+      if (response?.error) {
+        logger.error(`Registration error from server:`, response.error);
+        throw new Error(
+          `Server error: ${response.error.message || "Unknown error"}`
+        );
+      }
+
+      // Extract result from JSONRPC response structure
+      const result = response?.result;
+
+      if (result?.runnerId) {
+        this.config.runnerId = result.runnerId;
+        this.runnerUid = result.runnerUid;
+        this.lastProcessedAt = result.lastProcessedAt
+          ? new Date(result.lastProcessedAt)
+          : null;
+        this.isRegistered = true;
+
+        // Save registration state
+        await this.stateManager.updateRunnerRegistration(
+          result.runnerId,
+          result.runnerUid,
+          this.lastProcessedAt
+        );
+
+        logger.info(
+          `Runner registered successfully with ID: ${this.config.runnerId} and UID: ${this.runnerUid}`
+        );
+
+        // Process runnerRepos from response
+        if (result.runnerRepos && Array.isArray(result.runnerRepos)) {
+          await this.updateRunnerReposWithIds(result.runnerRepos);
+        }
+
+        // Debug logging for registration details
+        if (process.env["DEBUG"] === "true") {
+          logger.debug("Registration complete with details", {
+            runnerId: this.config.runnerId,
+            runnerUid: this.runnerUid,
+            lastProcessedAt: this.lastProcessedAt?.toISOString() || "null",
+            orchestratorUrl: this.config.orchestratorUrl,
+            dataDir: this.config.dataDir,
+            runnerReposCount: result.runnerRepos?.length || 0,
+          });
+        }
+      } else {
+        logger.error(`Registration failed. Expected result.runnerId but got:`, {
+          hasResult: !!result,
+          resultKeys: result ? Object.keys(result) : [],
+          fullResponse: JSON.stringify(response, null, 2),
+        });
+        throw new Error("Registration response did not include runnerId");
+      }
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      logger.error(`Failed to register runner: ${errorMessage}`);
+      throw error;
+    }
+  }
+
+  private async registerWithRetry(): Promise<void> {
+    const strategy = this.config.retryStrategy;
+
+    if (strategy === "none") {
+      // Single attempt, no retries
+      await this.registerRunner();
+      return;
+    }
+
+    if (strategy === "interval") {
+      // Retry at fixed intervals
+      const intervalMs = this.config.retryIntervalSecs * 1000;
+      let attempt = 0;
+
+      while (!this.isRegistered) {
+        attempt++;
+        try {
+          logger.info(`Registration attempt ${attempt}...`);
+          await this.registerRunner();
+          return;
+        } catch (error) {
+          const errorMessage =
+            error instanceof Error ? error.message : String(error);
+          logger.error(
+            `Registration attempt ${attempt} failed: ${errorMessage}`
+          );
+          logger.info(
+            `Retrying in ${this.config.retryIntervalSecs} seconds...`
+          );
+          await this.delayFn(intervalMs);
+        }
+      }
+    }
+
+    if (strategy === "exponential") {
+      // Exponential backoff with max duration
+      const maxDurationMs = this.config.retryDurationSecs * 1000;
+      const startTime = Date.now();
+      let delayMs = 8000; // Start with 8 seconds
+      let attempt = 0;
+
+      while (!this.isRegistered) {
+        attempt++;
+        try {
+          logger.info(`Registration attempt ${attempt}...`);
+          await this.registerRunner();
+          return;
+        } catch (error) {
+          const errorMessage =
+            error instanceof Error ? error.message : String(error);
+          logger.error(
+            `Registration attempt ${attempt} failed: ${errorMessage}`
+          );
+
+          const elapsedMs = Date.now() - startTime;
+          if (elapsedMs >= maxDurationMs) {
+            // Final retry at max duration
+            const remainingMs = maxDurationMs - elapsedMs;
+            if (remainingMs > 0) {
+              logger.info(
+                `Final retry in ${Math.ceil(remainingMs / 1000)} seconds...`
+              );
+              await this.delayFn(remainingMs);
+
+              try {
+                logger.info("Final registration attempt...");
+                await this.registerRunner();
+                return;
+              } catch (finalError) {
+                const errorMessage =
+                  finalError instanceof Error
+                    ? finalError.message
+                    : String(finalError);
+                logger.error(
+                  `Final registration attempt failed: ${errorMessage}`
+                );
+                throw new Error(
+                  `Failed to register after ${this.config.retryDurationSecs} seconds`
+                );
+              }
+            } else {
+              throw new Error(
+                `Failed to register after ${this.config.retryDurationSecs} seconds`
+              );
+            }
+          }
+
+          // Calculate next delay with exponential backoff
+          const nextDelayMs = Math.min(delayMs, maxDurationMs - elapsedMs);
+          logger.info(
+            `Retrying in ${Math.ceil(nextDelayMs / 1000)} seconds...`
+          );
+          await this.delayFn(nextDelayMs);
+
+          // Double the delay for next attempt
+          delayMs = Math.min(delayMs * 2, maxDurationMs);
+        }
+      }
+    }
+  }
+
+  /**
+   * Load runnerRepos for a specific runnerId from the config file
+   */
+  private async loadRunnerReposForId(runnerId: string): Promise<void> {
+    if (!this.configPath) {
+      logger.debug("No config path specified, cannot load runnerRepos");
+      return;
+    }
+
+    try {
+      const configContent = await fs.readFile(
+        path.resolve(this.configPath),
+        "utf-8"
+      );
+      const configFile = JSON.parse(configContent);
+
+      if (!configFile.runnerRepos || typeof configFile.runnerRepos !== "object") {
+        logger.debug("No runnerRepos in config file");
+        this.config.runnerRepos = [];
+        return;
+      }
+
+      const reposForThisRunner = configFile.runnerRepos[runnerId];
+      if (reposForThisRunner && Array.isArray(reposForThisRunner)) {
+        this.config.runnerRepos = reposForThisRunner;
+        logger.info(
+          `Loaded ${reposForThisRunner.length} runnerRepos for runner ${runnerId}`
+        );
+      } else {
+        this.config.runnerRepos = [];
+        logger.debug(
+          `No runnerRepos found for runner ${runnerId}, using empty array`
+        );
+      }
+    } catch (error) {
+      logger.error("Failed to load runnerRepos for runner", error);
+      this.config.runnerRepos = [];
+    }
+  }
+
+  private async updateRunnerReposWithIds(
+    serverRunnerRepos: any[]
+  ): Promise<void> {
+    if (!this.configPath || !this.config.runnerId) {
+      logger.info(
+        "No config path or runnerId specified, cannot update runnerRepos with IDs"
+      );
+      return;
+    }
+
+    try {
+      const { ConfigManager } = await import("./utils/config");
+      const configContent = await fs.readFile(
+        path.resolve(this.configPath),
+        "utf-8"
+      );
+      const configFile = JSON.parse(configContent);
+
+      // Initialize runnerRepos namespace if not present
+      if (!configFile.runnerRepos) {
+        configFile.runnerRepos = {};
+      }
+
+      // Get or create repos array for this runnerId
+      let reposForThisRunner = configFile.runnerRepos[this.config.runnerId];
+      if (!reposForThisRunner || !Array.isArray(reposForThisRunner)) {
+        reposForThisRunner = [];
+        configFile.runnerRepos[this.config.runnerId] = reposForThisRunner;
+      }
+
+      // Update runnerRepos with UUIDs from server
+      let hasUpdates = false;
+      for (const serverRepo of serverRunnerRepos) {
+        const localRepo = reposForThisRunner.find(
+          (r: RunnerRepo) =>
+            r.name === serverRepo.name && r.path === serverRepo.path
+        );
+
+        if (localRepo && serverRepo.uuid) {
+          // Store UUID if not already present or different
+          if (!localRepo.uuid || localRepo.uuid !== serverRepo.uuid) {
+            localRepo.uuid = serverRepo.uuid;
+            hasUpdates = true;
+            logger.info(
+              `Updated RunnerRepo "${localRepo.name}" with UUID: ${serverRepo.uuid}`
+            );
+          }
+        } else if (serverRepo.uuid) {
+          // Add new repo from server
+          reposForThisRunner.push({
+            uuid: serverRepo.uuid,
+            name: serverRepo.name,
+            path: serverRepo.path,
+          });
+          hasUpdates = true;
+          logger.info(
+            `Added new RunnerRepo "${serverRepo.name}" with UUID: ${serverRepo.uuid}`
+          );
+        }
+      }
+
+      // Save the updated config if there were changes
+      if (hasUpdates) {
+        await ConfigManager.saveConfigFile(this.configPath, configFile);
+        // Update our in-memory config
+        this.config.runnerRepos = reposForThisRunner;
+        logger.info(`Saved ${reposForThisRunner.length} runnerRepos for runner ${this.config.runnerId}`);
+      }
+    } catch (error) {
+      logger.error("Failed to update runnerRepos with IDs", error);
+    }
+  }
+
+  private async sendToOrchestratorWithRetry(
+    message: JsonRpcMessage
+  ): Promise<any> {
+    const maxRetries = 5;
+    const initialDelayMs = 1000; // Start with 1 second
+    const maxDelayMs = 60000; // Max 60 seconds
+    const jitterMs = 500; // Add up to 500ms of random jitter
+
+    let lastError: Error | undefined;
+
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        return await this.sendToOrchestrator(message);
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+
+        // Don't retry on certain errors
+        if (
+          lastError.message.includes("HTTP 401") ||
+          lastError.message.includes("HTTP 403") ||
+          lastError.message.includes("HTTP 404")
+        ) {
+          throw lastError;
+        }
+
+        if (attempt < maxRetries) {
+          // Calculate exponential backoff with jitter
+          const baseDelay = Math.min(
+            initialDelayMs * Math.pow(2, attempt),
+            maxDelayMs
+          );
+          const jitter = Math.random() * jitterMs;
+          const delayMs = baseDelay + jitter;
+
+          // Log retry attempt
+          const errorMessage = lastError.message || String(lastError);
+          if (message.method === "runner.heartbeat") {
+            // Less verbose for heartbeat retries
+            logger.debug(
+              `Heartbeat retry ${attempt + 1}/${maxRetries + 1} in ${Math.round(
+                delayMs
+              )}ms`
+            );
+          } else {
+            logger.warn(
+              `RPC retry ${attempt + 1}/${maxRetries + 1} for '${
+                message.method
+              }' after error: ${errorMessage}. Retrying in ${Math.round(
+                delayMs
+              )}ms`
+            );
+          }
+
+          await this.delayFn(delayMs);
+        }
+      }
+    }
+
+    // All retries exhausted
+    const finalError = lastError || new Error("Unknown error");
+    if (message.method !== "runner.heartbeat") {
+      logger.error(`RPC failed after ${maxRetries + 1} attempts:`, {
+        method: message.method,
+        error: finalError.message,
+      });
+    }
+    throw finalError;
+  }
+
+  private startHeartbeat(): void {
+    if (!this.isRegistered || !this.config.runnerId) {
+      logger.warn("Cannot start heartbeat: runner not registered");
+      return;
+    }
+
+    this.heartbeatInterval = setInterval(async () => {
+      try {
+        await this.notify("runner.heartbeat", {
+          runnerId: this.config.runnerId,
+          activeConversations: this.agentConversations.size,
+          uptime: process.uptime(),
+          memoryUsage: process.memoryUsage(),
+        });
+      } catch (error) {
+        // Error is already logged in notify() method
+      }
+    }, this.config.heartbeatInterval);
+  }
+
+  private async stopAllConversations(
+    isRunnerShutdown: boolean = true
+  ): Promise<void> {
+    const stopPromises: Promise<void>[] = [];
+
+    for (const [conversationId, context] of this.agentConversations) {
+      if (context.status === "active" || context.status === "starting") {
+        stopPromises.push(
+          this.claudeManager
+            .stopConversation(context.agentSessionId, context, isRunnerShutdown)
+            .catch((error) => {
+              logger.error(
+                `Failed to stop conversation ${context.agentSessionId}:`,
+                error
+              );
+            })
+        );
+      }
+    }
+
+    await Promise.all(stopPromises);
+    this.agentConversations.clear();
+  }
+
+  // Update lastProcessedAt and persist state
+  async updateLastProcessedAt(timestamp: Date | null): Promise<void> {
+    this.lastProcessedAt = timestamp;
+    if (timestamp) {
+      await this.stateManager.updateLastProcessedAt(timestamp);
+    }
+  }
+
+  // Getters for components
+  get config_(): RunnerConfig {
+    return this.config;
+  }
+
+  get activeConversations_(): Map<string, ConversationContext> {
+    return this.agentConversations;
+  }
+
+  get claudeManager_(): ClaudeManager {
+    return this.claudeManager;
+  }
+  get repositoryManager_(): EnhancedRepositoryManager {
+    return this.repositoryManager;
+  }
+
+  getRunnerId(): string | undefined {
+    return this.config.runnerId;
+  }
+
+  // UID ownership getters/setters
+  getRunnerUid(): string | null {
+    return this.runnerUid;
+  }
+
+  getLastProcessedAt(): Date | null {
+    return this.lastProcessedAt;
+  }
+
+  getIsActiveRunner(): boolean {
+    return this.isActiveRunner;
+  }
+
+  setIsActiveRunner(active: boolean): void {
+    const previousState = this.isActiveRunner;
+    this.isActiveRunner = active;
+
+    // Persist state change
+    this.stateManager.updateActiveStatus(active).catch((error) => {
+      logger.error("Failed to persist active status:", error);
+    });
+
+    if (process.env["DEBUG"] === "true") {
+      logger.debug("Active runner status changed", {
+        previous: previousState,
+        new: active,
+        runnerUid: this.runnerUid,
+        lastProcessedAt: this.lastProcessedAt?.toISOString() || "null",
+      });
+    }
+  }
+
+  setLastProcessedAt(timestamp: Date | null): void {
+    const previousTimestamp = this.lastProcessedAt;
+    this.lastProcessedAt = timestamp;
+
+    if (process.env["DEBUG"] === "true") {
+      logger.debug("LastProcessedAt updated", {
+        previous: previousTimestamp?.toISOString() || "null",
+        new: timestamp?.toISOString() || "null",
+        runnerUid: this.runnerUid,
+        isActiveRunner: this.isActiveRunner,
+      });
+    }
+  }
+
+  getPreHandoffConversations(): Set<string> {
+    return this.preHandoffConversations;
+  }
+
+  // For testing purposes - allows mocking delays
+  setDelayFunction(fn: (ms: number) => Promise<void>): void {
+    this.delayFn = fn;
+  }
+}