src/plugins/agents/base.ts (1)

622-701: Surface stderr on preflight failures for clearer diagnostics.
When the process exits non‑zero without an error event, result.error is empty, so users see a generic failure. Falling back to result.stderr gives more actionable feedback.

♻️ Suggested adjustment

-      if (result.status === 'failed') {
-        return {
-          success: false,
-          error: result.error ?? 'Agent execution failed',
-          suggestion: this.getPreflightSuggestion(),
-          durationMs,
-        };
-      }
+      if (result.status === 'failed') {
+        const failureDetail = result.error || result.stderr || 'Agent execution failed';
+        return {
+          success: false,
+          error: failureDetail,
+          suggestion: this.getPreflightSuggestion(),
+          durationMs,
+        };
+      }

src/setup/wizard.ts (1)

384-424: Consider disposing the agent instance after preflight check.

The agentInstance obtained from the registry is used for the preflight check but never disposed. While this may not cause immediate issues since the wizard exits shortly after, it's good practice to clean up resources.

Additionally, consider wrapping the getInstance call in a try-catch block to handle potential initialisation failures gracefully, similar to how the doctor command handles this.

♻️ Suggested improvement

     // Get a fresh agent instance with the configured options
     const agentRegistry = getAgentRegistry();
-    const agentInstance = await agentRegistry.getInstance({
-      name: selectedAgent,
-      plugin: selectedAgent,
-      options: agentOptions,
-    });
+    let agentInstance;
+    try {
+      agentInstance = await agentRegistry.getInstance({
+        name: selectedAgent,
+        plugin: selectedAgent,
+        options: agentOptions,
+      });
+    } catch (error) {
+      printError(`Failed to initialise agent: ${error instanceof Error ? error.message : String(error)}`);
+      printInfo('Configuration saved, but the agent could not be initialised.');
+      printInfo('Run "ralph-tui doctor" to diagnose issues.');
+      console.log();
+      // Continue to show tracker-specific instructions
+    }

-    // Run preflight check
-    const preflightResult = await agentInstance.preflight({ timeout: 30000 });
+    if (agentInstance) {
+      // Run preflight check
+      const preflightResult = await agentInstance.preflight({ timeout: 30000 });
+      // ... existing success/failure handling ...
+
+      // Clean up
+      await agentInstance.dispose();
+    }

src/commands/run.tsx (1)

1362-1395: Consider disposing the agent instance after preflight check.

Similar to the wizard implementation, the agentInstance obtained for the preflight check is not disposed after use. Whilst the process may exit on failure, on success the agent instance remains allocated until the next agent is instantiated for the actual run.

♻️ Suggested improvement

     const agentRegistry = getAgentRegistry();
     const agentInstance = await agentRegistry.getInstance(config.agent);

     const preflightResult = await agentInstance.preflight({ timeout: 30000 });

     if (preflightResult.success) {
       console.log('✓ Agent is ready');
       if (preflightResult.durationMs) {
         console.log(`  Response time: ${preflightResult.durationMs}ms`);
       }
       console.log('');
+      // Note: Don't dispose here as the registry may reuse the instance
     } else {
       console.error('');
       console.error('❌ Agent preflight check failed');
       // ... error handling ...
+      await agentInstance.dispose();
       process.exit(1);
     }

src/commands/doctor.ts (1)

38-128: Consider disposing the agent instance after diagnostics.

The agent instance obtained from the registry is never disposed after the diagnostics complete. This could leave resources allocated, particularly if the doctor command is used programmatically.

♻️ Suggested improvement

   // Run preflight
   log('\n  Step 2: Preflight (testing if agent can respond)...');
   log('    Running test prompt...');

   const preflight = await agent.preflight({ timeout: 30000 });

+  // Clean up agent resources
+  await agent.dispose();
+
   if (!preflight.success) {
     return {
       healthy: false,
       agent: { name: agent.meta.name, plugin: agent.meta.id },
       detection,
       preflight,
       message: preflight.error ?? 'Agent failed preflight check',
     };
   }

Note: You may also want to ensure disposal happens in the early return paths (lines 90-96) and wrap in try/finally for robustness.