🤖 refactor: lazy executor pattern for background processes

Moves from pre-registration to lazy executor creation/caching:

- Remove registerExecutor()/unregisterExecutor() from BackgroundProcessManager
- spawn() now takes executor as first arg, caches per workspace
- AIService creates executor alongside runtime in streamMessage()
- Remove ensureExecutorRegistered() and getWorkspaceMetadataSync()
- Remove 3 registration calls from IpcMain workspace creation paths

This follows the existing pattern where runtime is created on-demand
from metadata rather than pre-registered. Executors are still cached
for SSH connection pooling.

Net ~100 LoC removed.

Author: ethanndickson

src/common/utils/tools/tools.ts

@@ -16,6 +16,7 @@ import { log } from "@/node/services/log";
 import type { Runtime } from "@/node/runtime/Runtime";
 import type { InitStateManager } from "@/node/services/initStateManager";
 import type { BackgroundProcessManager } from "@/node/services/backgroundProcessManager";
+import type { BackgroundExecutor } from "@/node/services/backgroundExecutor";
 
 /**
  * Configuration for tools that need runtime context
@@ -35,6 +36,8 @@ export interface ToolConfiguration {
   overflow_policy?: "truncate" | "tmpfile";
   /** Background process manager for bash tool (optional, AI-only) */
   backgroundProcessManager?: BackgroundProcessManager;
+  /** Background executor for this workspace (optional, AI-only) */
+  backgroundExecutor?: BackgroundExecutor;
   /** Workspace ID for tracking background processes (optional for token estimation) */
   workspaceId?: string;
 }

src/node/config.ts

@@ -360,33 +360,6 @@ export class Config {
     return workspaceMetadata;
   }
 
-  /**
-   * Get workspace metadata by ID synchronously.
-   * Used for executor registration when creating sessions for existing workspaces.
-   * Only returns workspaces that have complete metadata in config (not legacy).
-   */
-  getWorkspaceMetadataSync(workspaceId: string): WorkspaceMetadata | null {
-    const config = this.loadConfigOrDefault();
-
-    for (const [projectPath, projectConfig] of config.projects) {
-      for (const workspace of projectConfig.workspaces) {
-        // Only check new format workspaces (have id and name in config)
-        if (workspace.id === workspaceId && workspace.name) {
-          return {
-            id: workspace.id,
-            name: workspace.name,
-            projectName: this.getProjectName(projectPath),
-            projectPath,
-            createdAt: workspace.createdAt,
-            runtimeConfig: workspace.runtimeConfig ?? DEFAULT_RUNTIME_CONFIG,
-          };
-        }
-      }
-    }
-
-    return null;
-  }
-
   /**
    * Add a workspace to config.json (single source of truth for workspace metadata).
    * Creates project entry if it doesn't exist.

src/node/services/aiService.ts

@@ -21,6 +21,12 @@ import { createRuntime } from "@/node/runtime/runtimeFactory";
 import { secretsToRecord } from "@/common/types/secrets";
 import type { MuxProviderOptions } from "@/common/types/providerOptions";
 import type { BackgroundProcessManager } from "@/node/services/backgroundProcessManager";
+import type { BackgroundExecutor } from "@/node/services/backgroundExecutor";
+import { LocalBackgroundExecutor } from "@/node/services/localBackgroundExecutor";
+import { SSHBackgroundExecutor } from "@/node/services/sshBackgroundExecutor";
+import { BashExecutionService } from "@/node/services/bashExecutionService";
+import { isSSHRuntime, type RuntimeConfig } from "@/common/types/runtime";
+import type { Runtime } from "@/node/runtime/Runtime";
 import { log } from "./log";
 import {
   transformModelMessages,
@@ -143,6 +149,7 @@ export class AIService extends EventEmitter {
   private readonly mockModeEnabled: boolean;
   private readonly mockScenarioPlayer?: MockScenarioPlayer;
   private readonly backgroundProcessManager?: BackgroundProcessManager;
+  private readonly bashExecutionService: BashExecutionService;
 
   constructor(
     config: Config,
@@ -160,6 +167,7 @@ export class AIService extends EventEmitter {
     this.partialService = partialService;
     this.initStateManager = initStateManager;
     this.backgroundProcessManager = backgroundProcessManager;
+    this.bashExecutionService = new BashExecutionService();
     this.streamManager = new StreamManager(historyService, partialService);
     void this.ensureSessionsDir();
     this.setupStreamEventForwarding();
@@ -173,6 +181,20 @@ export class AIService extends EventEmitter {
     }
   }
 
+  /**
+   * Create a background executor appropriate for the given runtime.
+   * Local runtimes use LocalBackgroundExecutor, SSH runtimes use SSHBackgroundExecutor.
+   */
+  private createBackgroundExecutor(
+    runtimeConfig: RuntimeConfig,
+    runtime: Runtime
+  ): BackgroundExecutor {
+    if (isSSHRuntime(runtimeConfig)) {
+      return new SSHBackgroundExecutor(runtime);
+    }
+    return new LocalBackgroundExecutor(this.bashExecutionService);
+  }
+
   /**
    * Forward all stream events from StreamManager to AIService consumers
    */
@@ -719,16 +741,21 @@ export class AIService extends EventEmitter {
       }
 
       // Get workspace path - handle both worktree and in-place modes
-      const runtime = createRuntime(
-        metadata.runtimeConfig ?? { type: "local", srcBaseDir: this.config.srcDir }
-      );
+      const runtimeConfig = metadata.runtimeConfig ?? {
+        type: "local" as const,
+        srcBaseDir: this.config.srcDir,
+      };
+      const runtime = createRuntime(runtimeConfig);
       // In-place workspaces (CLI/benchmarks) have projectPath === name
       // Use path directly instead of reconstructing via getWorkspacePath
       const isInPlace = metadata.projectPath === metadata.name;
       const workspacePath = isInPlace
         ? metadata.projectPath
         : runtime.getWorkspacePath(metadata.projectPath, metadata.name);
 
+      // Create background executor for this workspace (cached on first spawn)
+      const backgroundExecutor = this.createBackgroundExecutor(runtimeConfig, runtime);
+
       // Build system message from workspace metadata
       const systemMessage = await buildSystemMessage(
         metadata,
@@ -767,6 +794,7 @@ export class AIService extends EventEmitter {
           secrets: secretsToRecord(projectSecrets),
           runtimeTempDir,
           backgroundProcessManager: this.backgroundProcessManager,
+          backgroundExecutor,
           workspaceId,
         },
         workspaceId,

src/node/services/backgroundProcessManager.test.ts

@@ -2,26 +2,27 @@ import { describe, it, expect, beforeEach } from "bun:test";
 import { BackgroundProcessManager } from "./backgroundProcessManager";
 import { BashExecutionService } from "./bashExecutionService";
 import { LocalBackgroundExecutor } from "./localBackgroundExecutor";
+import type { BackgroundExecutor } from "./backgroundExecutor";
 
-// Helper to create manager with executor registered for a workspace
-function createManagerWithExecutor(workspaceId: string): BackgroundProcessManager {
-  const manager = new BackgroundProcessManager();
-  manager.registerExecutor(workspaceId, new LocalBackgroundExecutor(new BashExecutionService()));
-  return manager;
+// Create a shared executor for tests
+function createTestExecutor(): BackgroundExecutor {
+  return new LocalBackgroundExecutor(new BashExecutionService());
 }
 
 describe("BackgroundProcessManager", () => {
   let manager: BackgroundProcessManager;
+  let executor: BackgroundExecutor;
   const testWorkspaceId = "workspace-1";
   const testWorkspaceId2 = "workspace-2";
 
   beforeEach(() => {
-    manager = createManagerWithExecutor(testWorkspaceId);
+    manager = new BackgroundProcessManager();
+    executor = createTestExecutor();
   });
 
   describe("spawn", () => {
     it("should spawn a background process and return process ID", async () => {
-      const result = await manager.spawn(testWorkspaceId, "echo hello", {
+      const result = await manager.spawn(executor, testWorkspaceId, "echo hello", {
         cwd: process.cwd(),
       });
 
@@ -31,28 +32,16 @@ describe("BackgroundProcessManager", () => {
       }
     });
 
-    it("should return error when no executor is registered", async () => {
-      const managerNoExecutor = new BackgroundProcessManager();
-      const result = await managerNoExecutor.spawn("unregistered-workspace", "echo hello", {
-        cwd: process.cwd(),
-      });
-
-      expect(result.success).toBe(false);
-      if (!result.success) {
-        expect(result.error).toContain("No executor registered");
-      }
-    });
-
     it("should return error on spawn failure", async () => {
-      const result = await manager.spawn(testWorkspaceId, "echo test", {
+      const result = await manager.spawn(executor, testWorkspaceId, "echo test", {
         cwd: "/nonexistent/path/that/does/not/exist",
       });
 
       expect(result.success).toBe(false);
     });
 
     it("should capture stdout and stderr", async () => {
-      const result = await manager.spawn(testWorkspaceId, "echo hello; echo world >&2", {
+      const result = await manager.spawn(executor, testWorkspaceId, "echo hello; echo world >&2", {
         cwd: process.cwd(),
       });
 
@@ -75,7 +64,7 @@ describe("BackgroundProcessManager", () => {
         .map((_, i) => `echo line${i}`)
         .join("; ");
 
-      const result = await manager.spawn(testWorkspaceId, script, {
+      const result = await manager.spawn(executor, testWorkspaceId, script, {
         cwd: process.cwd(),
       });
 
@@ -93,7 +82,7 @@ describe("BackgroundProcessManager", () => {
 
   describe("getProcess", () => {
     it("should return process by ID", async () => {
-      const spawnResult = await manager.spawn(testWorkspaceId, "sleep 1", {
+      const spawnResult = await manager.spawn(executor, testWorkspaceId, "sleep 1", {
         cwd: process.cwd(),
       });
 
@@ -113,22 +102,18 @@ describe("BackgroundProcessManager", () => {
 
   describe("list", () => {
     it("should list all processes", async () => {
-      await manager.spawn(testWorkspaceId, "sleep 1", { cwd: process.cwd() });
-      await manager.spawn(testWorkspaceId, "sleep 1", { cwd: process.cwd() });
+      await manager.spawn(executor, testWorkspaceId, "sleep 1", { cwd: process.cwd() });
+      await manager.spawn(executor, testWorkspaceId, "sleep 1", { cwd: process.cwd() });
 
       const processes = manager.list();
       expect(processes.length).toBeGreaterThanOrEqual(2);
     });
 
     it("should filter by workspace ID", async () => {
-      // Register second workspace executor
-      manager.registerExecutor(
-        testWorkspaceId2,
-        new LocalBackgroundExecutor(new BashExecutionService())
-      );
+      const executor2 = createTestExecutor();
 
-      await manager.spawn(testWorkspaceId, "sleep 1", { cwd: process.cwd() });
-      await manager.spawn(testWorkspaceId2, "sleep 1", { cwd: process.cwd() });
+      await manager.spawn(executor, testWorkspaceId, "sleep 1", { cwd: process.cwd() });
+      await manager.spawn(executor2, testWorkspaceId2, "sleep 1", { cwd: process.cwd() });
 
       const ws1Processes = manager.list(testWorkspaceId);
       const ws2Processes = manager.list(testWorkspaceId2);
@@ -142,7 +127,7 @@ describe("BackgroundProcessManager", () => {
 
   describe("terminate", () => {
     it("should terminate a running process", async () => {
-      const spawnResult = await manager.spawn(testWorkspaceId, "sleep 10", {
+      const spawnResult = await manager.spawn(executor, testWorkspaceId, "sleep 10", {
         cwd: process.cwd(),
       });
 
@@ -161,7 +146,7 @@ describe("BackgroundProcessManager", () => {
     });
 
     it("should be idempotent (double-terminate succeeds)", async () => {
-      const spawnResult = await manager.spawn(testWorkspaceId, "sleep 10", {
+      const spawnResult = await manager.spawn(executor, testWorkspaceId, "sleep 10", {
         cwd: process.cwd(),
       });
 
@@ -176,29 +161,19 @@ describe("BackgroundProcessManager", () => {
   });
 
   describe("cleanup", () => {
-    it("should kill all processes for a workspace and remove them from memory", async () => {
-      // Register second workspace executor
-      manager.registerExecutor(
-        testWorkspaceId2,
-        new LocalBackgroundExecutor(new BashExecutionService())
-      );
+    it("should kill all processes for a workspace and clear cached executor", async () => {
+      const executor2 = createTestExecutor();
 
-      await manager.spawn(testWorkspaceId, "sleep 10", { cwd: process.cwd() });
-      await manager.spawn(testWorkspaceId, "sleep 10", { cwd: process.cwd() });
-      await manager.spawn(testWorkspaceId2, "sleep 10", { cwd: process.cwd() });
+      await manager.spawn(executor, testWorkspaceId, "sleep 10", { cwd: process.cwd() });
+      await manager.spawn(executor, testWorkspaceId, "sleep 10", { cwd: process.cwd() });
+      await manager.spawn(executor2, testWorkspaceId2, "sleep 10", { cwd: process.cwd() });
 
       await manager.cleanup(testWorkspaceId);
 
       const ws1Processes = manager.list(testWorkspaceId);
       const ws2Processes = manager.list(testWorkspaceId2);
       // All testWorkspaceId processes should be removed from memory
       expect(ws1Processes.length).toBe(0);
-      // Executor should also be unregistered - spawning should fail
-      const spawnResult = await manager.spawn(testWorkspaceId, "echo test", { cwd: process.cwd() });
-      expect(spawnResult.success).toBe(false);
-      if (!spawnResult.success) {
-        expect(spawnResult.error).toContain("No executor registered");
-      }
       // workspace-2 processes should still exist and be running
       expect(ws2Processes.length).toBeGreaterThanOrEqual(1);
       expect(ws2Processes.some((p) => p.status === "running")).toBe(true);
@@ -207,7 +182,7 @@ describe("BackgroundProcessManager", () => {
 
   describe("process state tracking", () => {
     it("should track process exit", async () => {
-      const result = await manager.spawn(testWorkspaceId, "exit 42", {
+      const result = await manager.spawn(executor, testWorkspaceId, "exit 42", {
         cwd: process.cwd(),
       });
 
@@ -223,7 +198,7 @@ describe("BackgroundProcessManager", () => {
     });
 
     it("should keep buffer after process exits", async () => {
-      const result = await manager.spawn(testWorkspaceId, "echo test; exit 0", {
+      const result = await manager.spawn(executor, testWorkspaceId, "echo test; exit 0", {
         cwd: process.cwd(),
       });
 
@@ -238,7 +213,7 @@ describe("BackgroundProcessManager", () => {
 
     it("should preserve killed status after onExit callback fires", async () => {
       // Spawn a long-running process
-      const result = await manager.spawn(testWorkspaceId, "sleep 60", {
+      const result = await manager.spawn(executor, testWorkspaceId, "sleep 60", {
         cwd: process.cwd(),
       });