🤖 fix: register background executors for existing workspaces after restart

- Add ensureExecutorRegistered() called from getOrCreateSession()
- Add Config.getWorkspaceMetadataSync() for sync metadata lookup
- Make registerExecutor() idempotent (no-op if already registered)

Without this fix, background execution tools failed for all pre-existing
workspaces after app restart with 'No executor registered' error.

Author: ethanndickson

src/node/config.ts

@@ -360,6 +360,33 @@ 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/backgroundProcessManager.ts

@@ -33,10 +33,14 @@ export class BackgroundProcessManager {
 
   /**
    * Register an executor for a workspace.
-   * Called when workspace is created - local workspaces get LocalBackgroundExecutor,
-   * SSH workspaces get SSHBackgroundExecutor.
+   * Called when workspace is created or session is started for existing workspace.
+   * Local workspaces get LocalBackgroundExecutor, SSH workspaces get SSHBackgroundExecutor.
+   * Idempotent - no-op if executor already registered.
    */
   registerExecutor(workspaceId: string, executor: BackgroundExecutor): void {
+    if (this.executors.has(workspaceId)) {
+      return; // Already registered
+    }
     log.debug(`BackgroundProcessManager.registerExecutor(${workspaceId})`);
     this.executors.set(workspaceId, executor);
   }
@@ -65,7 +69,8 @@ export class BackgroundProcessManager {
     if (!executor) {
       return {
         success: false,
-        error: "No executor registered for this workspace. Background execution may not be supported.",
+        error:
+          "No executor registered for this workspace. Background execution may not be supported.",
       };
     }
 
@@ -194,7 +199,7 @@ export class BackgroundProcessManager {
       proc.exitTime ??= Date.now();
       // Ensure handle is cleaned up even on error
       if (proc.handle) {
-        await proc.handle.dispose().catch(() => {});
+        await proc.handle.dispose();
       }
       return { success: true };
     }

src/node/services/ipcMain.ts

@@ -121,6 +121,25 @@ export class IpcMain {
     return new LocalBackgroundExecutor(this.bashExecutionService);
   }
 
+  /**
+   * Ensure a background executor is registered for a workspace.
+   * Called when creating sessions for existing workspaces (after app restart).
+   * No-op if executor already registered or workspace not found (new workspace being created).
+   */
+  private ensureExecutorRegistered(workspaceId: string): void {
+    // Look up workspace metadata synchronously from config
+    const metadata = this.config.getWorkspaceMetadataSync(workspaceId);
+    if (!metadata) {
+      // Workspace not in config yet - executor will be registered by creation path
+      return;
+    }
+
+    const runtime = createRuntime(metadata.runtimeConfig);
+    const executor = this.createBackgroundExecutor(metadata.runtimeConfig, runtime);
+    // registerExecutor is idempotent - no-op if already registered
+    this.backgroundProcessManager.registerExecutor(workspaceId, executor);
+  }
+
   /**
    * Initialize the service. Call this after construction.
    * This is separate from the constructor to support async initialization.
@@ -420,6 +439,9 @@ export class IpcMain {
       return session;
     }
 
+    // Ensure executor is registered for existing workspaces (handles app restart case)
+    this.ensureExecutorRegistered(trimmed);
+
     session = new AgentSession({
       workspaceId: trimmed,
       config: this.config,

src/node/services/localBackgroundExecutor.ts

@@ -88,8 +88,8 @@ class LocalBackgroundHandle implements BackgroundHandle {
     }
   }
 
-  async isRunning(): Promise<boolean> {
-    return this.disposable.child.exitCode === null;
+  isRunning(): Promise<boolean> {
+    return Promise.resolve(this.disposable.child.exitCode === null);
   }
 
   async terminate(): Promise<void> {
@@ -126,8 +126,8 @@ class LocalBackgroundHandle implements BackgroundHandle {
     this.terminated = true;
   }
 
-  async dispose(): Promise<void> {
-    this.disposable[Symbol.dispose]();
+  dispose(): Promise<void> {
+    return Promise.resolve(this.disposable[Symbol.dispose]());
   }
 
   /** Get the child process (for spawn event waiting) */
@@ -145,7 +145,9 @@ export class LocalBackgroundExecutor implements BackgroundExecutor {
   async spawn(script: string, config: BackgroundExecConfig): Promise<BackgroundSpawnResult> {
     log.debug(`LocalBackgroundExecutor: Spawning background process in ${config.cwd}`);
 
-    // Create handle first so we can wire up callbacks
+    // Declare handle before executeStreaming so callbacks can reference it via closure.
+    // It's assigned immediately after executeStreaming returns, before any callbacks fire.
+    // eslint-disable-next-line prefer-const
     let handle: LocalBackgroundHandle;
 
     // Spawn with streaming callbacks that forward to handle
@@ -190,9 +192,7 @@ export class LocalBackgroundExecutor implements BackgroundExecutor {
       return { success: false, error: err.message };
     }
 
-    log.debug(
-      `LocalBackgroundExecutor: Process spawned with PID ${handle.child.pid ?? "unknown"}`
-    );
+    log.debug(`LocalBackgroundExecutor: Process spawned with PID ${handle.child.pid ?? "unknown"}`);
     return { success: true, handle };
   }
 }

src/node/services/sshBackgroundExecutor.ts

@@ -32,12 +32,12 @@ export class SSHBackgroundExecutor implements BackgroundExecutor {
     // Runtime will be used for SSH commands when implemented
   }
 
-  async spawn(_script: string, _config: BackgroundExecConfig): Promise<BackgroundSpawnResult> {
+  spawn(_script: string, _config: BackgroundExecConfig): Promise<BackgroundSpawnResult> {
     // TODO: Implement SSH background execution
     // See file header for implementation approach
-    return {
+    return Promise.resolve({
       success: false,
       error: "SSH background execution is not yet implemented",
-    };
+    });
   }
 }

src/node/services/tools/bash.test.ts

@@ -1368,7 +1368,10 @@ describe("bash tool - background execution", () => {
 
   it("should reject timeout with background mode", async () => {
     const manager = new BackgroundProcessManager();
-    manager.registerExecutor("test-workspace", new LocalBackgroundExecutor(new BashExecutionService()));
+    manager.registerExecutor(
+      "test-workspace",
+      new LocalBackgroundExecutor(new BashExecutionService())
+    );
 
     const tempDir = new TestTempDir("test-bash-bg");
     const config = createTestToolConfig(process.cwd());
@@ -1395,7 +1398,10 @@ describe("bash tool - background execution", () => {
 
   it("should start background process and return process ID", async () => {
     const manager = new BackgroundProcessManager();
-    manager.registerExecutor("test-workspace", new LocalBackgroundExecutor(new BashExecutionService()));
+    manager.registerExecutor(
+      "test-workspace",
+      new LocalBackgroundExecutor(new BashExecutionService())
+    );
 
     const tempDir = new TestTempDir("test-bash-bg");
     const config = createTestToolConfig(process.cwd());

src/node/services/tools/bash_background_list.test.ts

@@ -110,8 +110,14 @@ describe("bash_background_list tool", () => {
 
   it("should only list processes for the current workspace", async () => {
     const manager = new BackgroundProcessManager();
-    manager.registerExecutor("workspace-a", new LocalBackgroundExecutor(new BashExecutionService()));
-    manager.registerExecutor("workspace-b", new LocalBackgroundExecutor(new BashExecutionService()));
+    manager.registerExecutor(
+      "workspace-a",
+      new LocalBackgroundExecutor(new BashExecutionService())
+    );
+    manager.registerExecutor(
+      "workspace-b",
+      new LocalBackgroundExecutor(new BashExecutionService())
+    );
 
     const tempDir = new TestTempDir("test-bash-bg-list");
     const config = createTestToolConfig(process.cwd(), { workspaceId: "workspace-a" });

src/node/services/tools/bash_background_read.test.ts

@@ -206,8 +206,14 @@ describe("bash_background_read tool", () => {
 
   it("should not read processes from other workspaces", async () => {
     const manager = new BackgroundProcessManager();
-    manager.registerExecutor("workspace-a", new LocalBackgroundExecutor(new BashExecutionService()));
-    manager.registerExecutor("workspace-b", new LocalBackgroundExecutor(new BashExecutionService()));
+    manager.registerExecutor(
+      "workspace-a",
+      new LocalBackgroundExecutor(new BashExecutionService())
+    );
+    manager.registerExecutor(
+      "workspace-b",
+      new LocalBackgroundExecutor(new BashExecutionService())
+    );
 
     const tempDir = new TestTempDir("test-bash-bg-read");
     // Config is for workspace-a

src/node/services/tools/bash_background_terminate.test.ts

@@ -144,8 +144,14 @@ describe("bash_background_terminate tool", () => {
 
   it("should not terminate processes from other workspaces", async () => {
     const manager = new BackgroundProcessManager();
-    manager.registerExecutor("workspace-a", new LocalBackgroundExecutor(new BashExecutionService()));
-    manager.registerExecutor("workspace-b", new LocalBackgroundExecutor(new BashExecutionService()));
+    manager.registerExecutor(
+      "workspace-a",
+      new LocalBackgroundExecutor(new BashExecutionService())
+    );
+    manager.registerExecutor(
+      "workspace-b",
+      new LocalBackgroundExecutor(new BashExecutionService())
+    );
 
     const tempDir = new TestTempDir("test-bash-bg-term");
     // Config is for workspace-a