fix(server): Address PR #733 review feedback and fix cross-platform tests

- Extract merge logic from pipeline-orchestrator to merge-service.ts to avoid HTTP self-call
- Make agent-executor error handling provider-agnostic using shared isAuthenticationError utility
- Fix cross-platform path handling in tests using path.normalize/path.resolve helpers
- Add catch handlers in plan-approval-service tests to prevent unhandled promise rejection warnings

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

apps/server/src/routes/worktree/routes/init-git.ts

@@ -43,10 +43,14 @@ export function createInitGitHandler() {
         // .git doesn't exist, continue with initialization
       }
 
-      // Initialize git and create an initial empty commit
-      await execAsync(`git init && git commit --allow-empty -m "Initial commit"`, {
-        cwd: projectPath,
-      });
+      // Initialize git with 'main' as the default branch (matching GitHub's standard since 2020)
+      // and create an initial empty commit
+      await execAsync(
+        `git init --initial-branch=main && git commit --allow-empty -m "Initial commit"`,
+        {
+          cwd: projectPath,
+        }
+      );
 
       res.json({
         success: true,

apps/server/src/services/agent-executor.ts

@@ -4,7 +4,7 @@
 
 import path from 'path';
 import type { ExecuteOptions, ParsedTask } from '@automaker/types';
-import { buildPromptWithImages, createLogger } from '@automaker/utils';
+import { buildPromptWithImages, createLogger, isAuthenticationError } from '@automaker/utils';
 import { getFeatureDir } from '@automaker/platform';
 import * as secureFs from '../lib/secure-fs.js';
 import { TypedEventBus } from './typed-event-bus.js';
@@ -206,14 +206,10 @@ export class AgentExecutor {
                   responseText += '\n\n';
               }
               responseText += newText;
-              if (
-                block.text &&
-                (block.text.includes('Invalid API key') ||
-                  block.text.includes('authentication_failed') ||
-                  block.text.includes('Fix external API key'))
-              )
+              // Check for authentication errors using provider-agnostic utility
+              if (block.text && isAuthenticationError(block.text))
                 throw new Error(
-                  "Authentication failed: Invalid or expired API key. Please check your ANTHROPIC_API_KEY, or run 'claude login' to re-authenticate."
+                  'Authentication failed: Invalid or expired API key. Please check your API key configuration or re-authenticate with your provider.'
                 );
               scheduleWrite();
               const hasExplicitMarker = responseText.includes('[SPEC_GENERATED]'),

apps/server/src/services/merge-service.ts

@@ -0,0 +1,175 @@
+/**
+ * MergeService - Direct merge operations without HTTP
+ *
+ * Extracted from worktree merge route to allow internal service calls.
+ */
+
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import { createLogger } from '@automaker/utils';
+import { spawnProcess } from '@automaker/platform';
+
+const execAsync = promisify(exec);
+const logger = createLogger('MergeService');
+
+export interface MergeOptions {
+  squash?: boolean;
+  message?: string;
+  deleteWorktreeAndBranch?: boolean;
+}
+
+export interface MergeServiceResult {
+  success: boolean;
+  error?: string;
+  hasConflicts?: boolean;
+  mergedBranch?: string;
+  targetBranch?: string;
+  deleted?: {
+    worktreeDeleted: boolean;
+    branchDeleted: boolean;
+  };
+}
+
+/**
+ * Execute git command with array arguments to prevent command injection.
+ */
+async function execGitCommand(args: string[], cwd: string): Promise<string> {
+  const result = await spawnProcess({
+    command: 'git',
+    args,
+    cwd,
+  });
+
+  if (result.exitCode === 0) {
+    return result.stdout;
+  } else {
+    const errorMessage = result.stderr || `Git command failed with code ${result.exitCode}`;
+    throw new Error(errorMessage);
+  }
+}
+
+/**
+ * Validate branch name to prevent command injection.
+ */
+function isValidBranchName(name: string): boolean {
+  return /^[a-zA-Z0-9._\-/]+$/.test(name) && name.length < 250;
+}
+
+/**
+ * Perform a git merge operation directly without HTTP.
+ *
+ * @param projectPath - Path to the git repository
+ * @param branchName - Source branch to merge
+ * @param worktreePath - Path to the worktree (used for deletion if requested)
+ * @param targetBranch - Branch to merge into (defaults to 'main')
+ * @param options - Merge options (squash, message, deleteWorktreeAndBranch)
+ */
+export async function performMerge(
+  projectPath: string,
+  branchName: string,
+  worktreePath: string,
+  targetBranch: string = 'main',
+  options?: MergeOptions
+): Promise<MergeServiceResult> {
+  if (!projectPath || !branchName || !worktreePath) {
+    return {
+      success: false,
+      error: 'projectPath, branchName, and worktreePath are required',
+    };
+  }
+
+  const mergeTo = targetBranch || 'main';
+
+  // Validate source branch exists
+  try {
+    await execAsync(`git rev-parse --verify ${branchName}`, { cwd: projectPath });
+  } catch {
+    return {
+      success: false,
+      error: `Branch "${branchName}" does not exist`,
+    };
+  }
+
+  // Validate target branch exists
+  try {
+    await execAsync(`git rev-parse --verify ${mergeTo}`, { cwd: projectPath });
+  } catch {
+    return {
+      success: false,
+      error: `Target branch "${mergeTo}" does not exist`,
+    };
+  }
+
+  // Merge the feature branch into the target branch
+  const mergeCmd = options?.squash
+    ? `git merge --squash ${branchName}`
+    : `git merge ${branchName} -m "${options?.message || `Merge ${branchName} into ${mergeTo}`}"`;
+
+  try {
+    await execAsync(mergeCmd, { cwd: projectPath });
+  } catch (mergeError: unknown) {
+    // Check if this is a merge conflict
+    const err = mergeError as { stdout?: string; stderr?: string; message?: string };
+    const output = `${err.stdout || ''} ${err.stderr || ''} ${err.message || ''}`;
+    const hasConflicts = output.includes('CONFLICT') || output.includes('Automatic merge failed');
+
+    if (hasConflicts) {
+      return {
+        success: false,
+        error: `Merge CONFLICT: Automatic merge of "${branchName}" into "${mergeTo}" failed. Please resolve conflicts manually.`,
+        hasConflicts: true,
+      };
+    }
+
+    // Re-throw non-conflict errors
+    throw mergeError;
+  }
+
+  // If squash merge, need to commit
+  if (options?.squash) {
+    await execAsync(`git commit -m "${options?.message || `Merge ${branchName} (squash)`}"`, {
+      cwd: projectPath,
+    });
+  }
+
+  // Optionally delete the worktree and branch after merging
+  let worktreeDeleted = false;
+  let branchDeleted = false;
+
+  if (options?.deleteWorktreeAndBranch) {
+    // Remove the worktree
+    try {
+      await execGitCommand(['worktree', 'remove', worktreePath, '--force'], projectPath);
+      worktreeDeleted = true;
+    } catch {
+      // Try with prune if remove fails
+      try {
+        await execGitCommand(['worktree', 'prune'], projectPath);
+        worktreeDeleted = true;
+      } catch {
+        logger.warn(`Failed to remove worktree: ${worktreePath}`);
+      }
+    }
+
+    // Delete the branch (but not main/master)
+    if (branchName !== 'main' && branchName !== 'master') {
+      if (!isValidBranchName(branchName)) {
+        logger.warn(`Invalid branch name detected, skipping deletion: ${branchName}`);
+      } else {
+        try {
+          await execGitCommand(['branch', '-D', branchName], projectPath);
+          branchDeleted = true;
+        } catch {
+          logger.warn(`Failed to delete branch: ${branchName}`);
+        }
+      }
+    }
+  }
+
+  return {
+    success: true,
+    mergedBranch: branchName,
+    targetBranch: mergeTo,
+    deleted: options?.deleteWorktreeAndBranch ? { worktreeDeleted, branchDeleted } : undefined,
+  };
+}

apps/server/src/services/pipeline-orchestrator.ts

@@ -27,6 +27,7 @@ import type { SettingsService } from './settings-service.js';
 import type { ConcurrencyManager } from './concurrency-manager.js';
 import { pipelineService } from './pipeline-service.js';
 import type { TestRunnerService, TestRunStatus } from './test-runner-service.js';
+import { performMerge } from './merge-service.js';
 import type {
   PipelineContext,
   PipelineStatusInfo,
@@ -65,8 +66,7 @@ export class PipelineOrchestrator {
     private loadContextFilesFn: typeof loadContextFiles,
     private buildFeaturePromptFn: BuildFeaturePromptFn,
     private executeFeatureFn: ExecuteFeatureFn,
-    private runAgentFn: RunAgentFn,
-    private serverPort = 3008
+    private runAgentFn: RunAgentFn
   ) {}
 
   async executePipeline(ctx: PipelineContext): Promise<void> {
@@ -483,37 +483,19 @@ export class PipelineOrchestrator {
 
     logger.info(`Attempting auto-merge for feature ${featureId} (branch: ${branchName})`);
     try {
-      const response = await fetch(`http://localhost:${this.serverPort}/api/worktree/merge`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({
-          projectPath,
-          branchName,
-          worktreePath,
-          targetBranch: 'main',
-          options: { deleteWorktreeAndBranch: false },
-        }),
-      });
+      // Call merge service directly instead of HTTP fetch
+      const result = await performMerge(
+        projectPath,
+        branchName,
+        worktreePath || projectPath,
+        'main',
+        {
+          deleteWorktreeAndBranch: false,
+        }
+      );
 
-      if (!response) {
-        return { success: false, error: 'No response from merge endpoint' };
-      }
-
-      // Defensively parse JSON response
-      let data: { success: boolean; hasConflicts?: boolean; error?: string };
-      try {
-        data = (await response.json()) as {
-          success: boolean;
-          hasConflicts?: boolean;
-          error?: string;
-        };
-      } catch (parseError) {
-        logger.error(`Failed to parse merge response:`, parseError);
-        return { success: false, error: 'Invalid response from merge endpoint' };
-      }
-
-      if (!response.ok) {
-        if (data.hasConflicts) {
+      if (!result.success) {
+        if (result.hasConflicts) {
           await this.updateFeatureStatusFn(projectPath, featureId, 'merge_conflict');
           this.eventBus.emitAutoModeEvent('pipeline_merge_conflict', {
             featureId,
@@ -522,7 +504,7 @@ export class PipelineOrchestrator {
           });
           return { success: false, hasConflicts: true, needsAgentResolution: true };
         }
-        return { success: false, error: data.error };
+        return { success: false, error: result.error };
       }
 
       logger.info(`Auto-merge successful for feature ${featureId}`);

apps/server/tests/integration/helpers/git-test-repo.ts

@@ -20,8 +20,8 @@ export interface TestRepo {
 export async function createTestGitRepo(): Promise<TestRepo> {
   const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'automaker-test-'));
 
-  // Initialize git repo
-  await execAsync('git init', { cwd: tmpDir });
+  // Initialize git repo with 'main' as the default branch (matching GitHub's standard)
+  await execAsync('git init --initial-branch=main', { cwd: tmpDir });
 
   // Use environment variables instead of git config to avoid affecting user's git config
   // These env vars override git config without modifying it
@@ -38,9 +38,6 @@ export async function createTestGitRepo(): Promise<TestRepo> {
   await execAsync('git add .', { cwd: tmpDir, env: gitEnv });
   await execAsync('git commit -m "Initial commit"', { cwd: tmpDir, env: gitEnv });
 
-  // Create main branch explicitly
-  await execAsync('git branch -M main', { cwd: tmpDir });
-
   return {
     path: tmpDir,
     cleanup: async () => {

apps/server/tests/integration/routes/worktree/create.integration.test.ts

@@ -14,7 +14,8 @@ describe('worktree create route - repositories without commits', () => {
 
   async function initRepoWithoutCommit() {
     repoPath = await fs.mkdtemp(path.join(os.tmpdir(), 'automaker-no-commit-'));
-    await execAsync('git init', { cwd: repoPath });
+    // Initialize with 'main' as the default branch (matching GitHub's standard)
+    await execAsync('git init --initial-branch=main', { cwd: repoPath });
     // Don't set git config - use environment variables in commit operations instead
     // to avoid affecting user's git config
     // Intentionally skip creating an initial commit

apps/server/tests/unit/services/dev-server-service.test.ts

@@ -30,11 +30,16 @@ import net from 'net';
 
 describe('dev-server-service.ts', () => {
   let testDir: string;
+  let originalHostname: string | undefined;
 
   beforeEach(async () => {
     vi.clearAllMocks();
     vi.resetModules();
 
+    // Store and set HOSTNAME for consistent test behavior
+    originalHostname = process.env.HOSTNAME;
+    process.env.HOSTNAME = 'localhost';
+
     testDir = path.join(os.tmpdir(), `dev-server-test-${Date.now()}`);
     await fs.mkdir(testDir, { recursive: true });
 
@@ -56,6 +61,13 @@ describe('dev-server-service.ts', () => {
   });
 
   afterEach(async () => {
+    // Restore original HOSTNAME
+    if (originalHostname === undefined) {
+      delete process.env.HOSTNAME;
+    } else {
+      process.env.HOSTNAME = originalHostname;
+    }
+
     try {
       await fs.rm(testDir, { recursive: true, force: true });
     } catch {

apps/server/tests/unit/services/execution-service.test.ts

@@ -1,5 +1,11 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import path from 'path';
 import type { Feature } from '@automaker/types';
+
+/**
+ * Helper to normalize paths for cross-platform test compatibility.
+ */
+const normalizePath = (p: string): string => path.resolve(p);
 import {
   ExecutionService,
   type RunAgentFn,
@@ -931,8 +937,8 @@ describe('execution-service.ts', () => {
       // Should still run agent, just with project path
       expect(mockRunAgentFn).toHaveBeenCalled();
       const callArgs = mockRunAgentFn.mock.calls[0];
-      // First argument is workDir - should end with /test/project
-      expect(callArgs[0]).toMatch(/\/test\/project$/);
+      // First argument is workDir - should be normalized path to /test/project
+      expect(callArgs[0]).toBe(normalizePath('/test/project'));
     });
 
     it('skips worktree resolution when useWorktrees is false', async () => {

apps/server/tests/unit/services/feature-state-manager.test.ts

@@ -1,4 +1,5 @@
 import { describe, it, expect, beforeEach, vi, type Mock } from 'vitest';
+import path from 'path';
 import { FeatureStateManager } from '@/services/feature-state-manager.js';
 import type { Feature } from '@automaker/types';
 import type { EventEmitter } from '@/lib/events.js';
@@ -8,6 +9,12 @@ import { atomicWriteJson, readJsonWithRecovery } from '@automaker/utils';
 import { getFeatureDir, getFeaturesDir } from '@automaker/platform';
 import { getNotificationService } from '@/services/notification-service.js';
 
+/**
+ * Helper to normalize paths for cross-platform test compatibility.
+ * Uses path.normalize (not path.resolve) to match path.join behavior in production code.
+ */
+const normalizePath = (p: string): string => path.normalize(p);
+
 // Mock dependencies
 vi.mock('@/lib/secure-fs.js', () => ({
   readFile: vi.fn(),
@@ -78,7 +85,7 @@ describe('FeatureStateManager', () => {
       expect(feature).toEqual(mockFeature);
       expect(getFeatureDir).toHaveBeenCalledWith('/project', 'feature-123');
       expect(readJsonWithRecovery).toHaveBeenCalledWith(
-        '/project/.automaker/features/feature-123/feature.json',
+        normalizePath('/project/.automaker/features/feature-123/feature.json'),
         null,
         expect.objectContaining({ autoRestore: true })
       );

apps/server/tests/unit/services/pipeline-orchestrator.test.ts

@@ -35,6 +35,13 @@ vi.mock('../../../src/services/pipeline-service.js', () => ({
   },
 }));
 
+// Mock merge-service
+vi.mock('../../../src/services/merge-service.js', () => ({
+  performMerge: vi.fn(),
+}));
+
+import { performMerge } from '../../../src/services/merge-service.js';
+
 // Mock secureFs
 vi.mock('../../../src/lib/secure-fs.js', () => ({
   readFile: vi.fn(),
@@ -470,36 +477,26 @@ describe('PipelineOrchestrator', () => {
     });
 
     beforeEach(() => {
-      global.fetch = vi.fn();
+      vi.mocked(performMerge).mockReset();
     });
 
-    afterEach(() => {
-      vi.mocked(global.fetch).mockReset();
-    });
-
-    it('should call merge endpoint with correct parameters', async () => {
-      vi.mocked(global.fetch).mockResolvedValue({
-        ok: true,
-        json: vi.fn().mockResolvedValue({ success: true }),
-      } as never);
+    it('should call performMerge with correct parameters', async () => {
+      vi.mocked(performMerge).mockResolvedValue({ success: true });
 
       const context = createMergeContext();
       await orchestrator.attemptMerge(context);
 
-      expect(global.fetch).toHaveBeenCalledWith(
-        expect.stringContaining('/api/worktree/merge'),
-        expect.objectContaining({
-          method: 'POST',
-          body: expect.stringContaining('feature/test-1'),
-        })
+      expect(performMerge).toHaveBeenCalledWith(
+        '/test/project',
+        'feature/test-1',
+        '/test/worktree',
+        'main',
+        { deleteWorktreeAndBranch: false }
       );
     });
 
     it('should return success on clean merge', async () => {
-      vi.mocked(global.fetch).mockResolvedValue({
-        ok: true,
-        json: vi.fn().mockResolvedValue({ success: true }),
-      } as never);
+      vi.mocked(performMerge).mockResolvedValue({ success: true });
 
       const context = createMergeContext();
       const result = await orchestrator.attemptMerge(context);
@@ -509,10 +506,11 @@ describe('PipelineOrchestrator', () => {
     });
 
     it('should set merge_conflict status when hasConflicts is true', async () => {
-      vi.mocked(global.fetch).mockResolvedValue({
-        ok: false,
-        json: vi.fn().mockResolvedValue({ success: false, hasConflicts: true }),
-      } as never);
+      vi.mocked(performMerge).mockResolvedValue({
+        success: false,
+        hasConflicts: true,
+        error: 'Merge conflict',
+      });
 
       const context = createMergeContext();
       await orchestrator.attemptMerge(context);
@@ -525,10 +523,11 @@ describe('PipelineOrchestrator', () => {
     });
 
     it('should emit pipeline_merge_conflict event on conflict', async () => {
-      vi.mocked(global.fetch).mockResolvedValue({
-        ok: false,
-        json: vi.fn().mockResolvedValue({ success: false, hasConflicts: true }),
-      } as never);
+      vi.mocked(performMerge).mockResolvedValue({
+        success: false,
+        hasConflicts: true,
+        error: 'Merge conflict',
+      });
 
       const context = createMergeContext();
       await orchestrator.attemptMerge(context);
@@ -540,10 +539,7 @@ describe('PipelineOrchestrator', () => {
     });
 
     it('should emit auto_mode_feature_complete on success', async () => {
-      vi.mocked(global.fetch).mockResolvedValue({
-        ok: true,
-        json: vi.fn().mockResolvedValue({ success: true }),
-      } as never);
+      vi.mocked(performMerge).mockResolvedValue({ success: true });
 
       const context = createMergeContext();
       await orchestrator.attemptMerge(context);
@@ -555,10 +551,11 @@ describe('PipelineOrchestrator', () => {
     });
 
     it('should return needsAgentResolution true on conflict', async () => {
-      vi.mocked(global.fetch).mockResolvedValue({
-        ok: false,
-        json: vi.fn().mockResolvedValue({ success: false, hasConflicts: true }),
-      } as never);
+      vi.mocked(performMerge).mockResolvedValue({
+        success: false,
+        hasConflicts: true,
+        error: 'Merge conflict',
+      });
 
       const context = createMergeContext();
       const result = await orchestrator.attemptMerge(context);
@@ -728,10 +725,7 @@ describe('PipelineOrchestrator', () => {
     });
 
     beforeEach(() => {
-      global.fetch = vi.fn().mockResolvedValue({
-        ok: true,
-        json: vi.fn().mockResolvedValue({ success: true }),
-      } as never);
+      vi.mocked(performMerge).mockResolvedValue({ success: true });
     });
 
     it('should execute steps in sequence', async () => {
@@ -792,9 +786,12 @@ describe('PipelineOrchestrator', () => {
       const context = createPipelineContext();
       await orchestrator.executePipeline(context);
 
-      expect(global.fetch).toHaveBeenCalledWith(
-        expect.stringContaining('/api/worktree/merge'),
-        expect.any(Object)
+      expect(performMerge).toHaveBeenCalledWith(
+        '/test/project',
+        'feature/test-1',
+        '/test/project', // Falls back to projectPath when worktreePath is null
+        'main',
+        { deleteWorktreeAndBranch: false }
       );
     });
   });
@@ -816,10 +813,7 @@ describe('PipelineOrchestrator', () => {
       });
 
       beforeEach(() => {
-        global.fetch = vi.fn().mockResolvedValue({
-          ok: true,
-          json: vi.fn().mockResolvedValue({ success: true }),
-        } as never);
+        vi.mocked(performMerge).mockResolvedValue({ success: true });
       });
 
       it('builds PipelineContext with correct fields from executeFeature', async () => {
@@ -845,11 +839,12 @@ describe('PipelineOrchestrator', () => {
         await orchestrator.executePipeline(context);
 
         // Merge should receive the worktree path
-        expect(global.fetch).toHaveBeenCalledWith(
-          expect.stringContaining('/api/worktree/merge'),
-          expect.objectContaining({
-            body: expect.stringContaining('/test/custom-worktree'),
-          })
+        expect(performMerge).toHaveBeenCalledWith(
+          '/test/project',
+          'feature/test-1',
+          '/test/custom-worktree',
+          'main',
+          { deleteWorktreeAndBranch: false }
         );
       });
 
@@ -860,11 +855,12 @@ describe('PipelineOrchestrator', () => {
 
         await orchestrator.executePipeline(context);
 
-        expect(global.fetch).toHaveBeenCalledWith(
-          expect.stringContaining('/api/worktree/merge'),
-          expect.objectContaining({
-            body: expect.stringContaining('feature/custom-branch'),
-          })
+        expect(performMerge).toHaveBeenCalledWith(
+          '/test/project',
+          'feature/custom-branch',
+          '/test/worktree',
+          'main',
+          { deleteWorktreeAndBranch: false }
         );
       });
 

apps/server/tests/unit/services/plan-approval-service.test.ts

@@ -54,6 +54,8 @@ describe('PlanApprovalService', () => {
 
     it('should timeout and reject after configured period', async () => {
       const approvalPromise = service.waitForApproval('feature-1', '/project');
+      // Attach catch to prevent unhandled rejection warning (will be properly asserted below)
+      approvalPromise.catch(() => {});
       // Flush the async initialization
       await vi.advanceTimersByTimeAsync(0);
 
@@ -73,6 +75,8 @@ describe('PlanApprovalService', () => {
       } as never);
 
       const approvalPromise = service.waitForApproval('feature-1', '/project');
+      // Attach catch to prevent unhandled rejection warning (will be properly asserted below)
+      approvalPromise.catch(() => {});
       // Flush the async initialization
       await vi.advanceTimersByTimeAsync(0);
 
@@ -93,6 +97,8 @@ describe('PlanApprovalService', () => {
       );
 
       const approvalPromise = serviceNoSettings.waitForApproval('feature-1', '/project');
+      // Attach catch to prevent unhandled rejection warning (will be properly asserted below)
+      approvalPromise.catch(() => {});
       // Flush async
       await vi.advanceTimersByTimeAsync(0);
 
@@ -417,6 +423,8 @@ describe('PlanApprovalService', () => {
       } as never);
 
       const approvalPromise = service.waitForApproval('feature-1', '/project');
+      // Attach catch to prevent unhandled rejection warning (will be properly asserted below)
+      approvalPromise.catch(() => {});
       await vi.advanceTimersByTimeAsync(0);
 
       // Should not timeout at 4 minutes
@@ -432,6 +440,8 @@ describe('PlanApprovalService', () => {
       vi.mocked(mockSettingsService!.getProjectSettings).mockRejectedValue(new Error('Failed'));
 
       const approvalPromise = service.waitForApproval('feature-1', '/project');
+      // Attach catch to prevent unhandled rejection warning (will be properly asserted below)
+      approvalPromise.catch(() => {});
       await vi.advanceTimersByTimeAsync(0);
 
       // Should use default 30 minute timeout
@@ -448,6 +458,8 @@ describe('PlanApprovalService', () => {
       } as never);
 
       const approvalPromise = service.waitForApproval('feature-1', '/project');
+      // Attach catch to prevent unhandled rejection warning (will be properly asserted below)
+      approvalPromise.catch(() => {});
       await vi.advanceTimersByTimeAsync(0);
 
       // Should use default 30 minute timeout

apps/server/tests/unit/services/recovery-service.test.ts

@@ -9,9 +9,16 @@
  */
 
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import path from 'path';
 import { RecoveryService, DEFAULT_EXECUTION_STATE } from '@/services/recovery-service.js';
 import type { Feature } from '@automaker/types';
 
+/**
+ * Helper to normalize paths for cross-platform test compatibility.
+ * Uses path.normalize (not path.resolve) to match path.join behavior in production code.
+ */
+const normalizePath = (p: string): string => path.normalize(p);
+
 // Mock dependencies
 vi.mock('@automaker/utils', () => ({
   createLogger: () => ({
@@ -288,7 +295,7 @@ describe('recovery-service.ts', () => {
 
       expect(result).toBe(true);
       expect(secureFs.access).toHaveBeenCalledWith(
-        '/test/project/.automaker/features/feature-1/agent-output.md'
+        normalizePath('/test/project/.automaker/features/feature-1/agent-output.md')
       );
     });
 

apps/server/tests/unit/services/worktree-resolver.test.ts

@@ -1,12 +1,20 @@
 import { describe, it, expect, beforeEach, vi, type Mock } from 'vitest';
 import { WorktreeResolver, type WorktreeInfo } from '@/services/worktree-resolver.js';
 import { exec } from 'child_process';
+import path from 'path';
 
 // Mock child_process
 vi.mock('child_process', () => ({
   exec: vi.fn(),
 }));
 
+/**
+ * Helper to normalize paths for cross-platform test compatibility.
+ * On Windows, path.resolve('/Users/dev/project') returns 'C:\Users\dev\project' (with current drive).
+ * This helper ensures test expectations match the actual platform behavior.
+ */
+const normalizePath = (p: string): string => path.resolve(p);
+
 // Create promisified mock helper
 const mockExecAsync = (
   impl: (cmd: string, options?: { cwd?: string }) => Promise<{ stdout: string; stderr: string }>
@@ -94,9 +102,9 @@ branch refs/heads/feature-y
     it('should find worktree by branch name', async () => {
       mockExecAsync(async () => ({ stdout: porcelainOutput, stderr: '' }));
 
-      const path = await resolver.findWorktreeForBranch('/Users/dev/project', 'feature-x');
+      const result = await resolver.findWorktreeForBranch('/Users/dev/project', 'feature-x');
 
-      expect(path).toBe('/Users/dev/project/.worktrees/feature-x');
+      expect(result).toBe(normalizePath('/Users/dev/project/.worktrees/feature-x'));
     });
 
     it('should return null when branch not found', async () => {
@@ -120,9 +128,9 @@ branch refs/heads/feature-y
     it('should find main worktree', async () => {
       mockExecAsync(async () => ({ stdout: porcelainOutput, stderr: '' }));
 
-      const path = await resolver.findWorktreeForBranch('/Users/dev/project', 'main');
+      const result = await resolver.findWorktreeForBranch('/Users/dev/project', 'main');
 
-      expect(path).toBe('/Users/dev/project');
+      expect(result).toBe(normalizePath('/Users/dev/project'));
     });
 
     it('should handle porcelain output without trailing newline', async () => {
@@ -134,9 +142,9 @@ branch refs/heads/feature-x`;
 
       mockExecAsync(async () => ({ stdout: noTrailingNewline, stderr: '' }));
 
-      const path = await resolver.findWorktreeForBranch('/Users/dev/project', 'feature-x');
+      const result = await resolver.findWorktreeForBranch('/Users/dev/project', 'feature-x');
 
-      expect(path).toBe('/Users/dev/project/.worktrees/feature-x');
+      expect(result).toBe(normalizePath('/Users/dev/project/.worktrees/feature-x'));
     });
 
     it('should resolve relative paths to absolute', async () => {
@@ -151,8 +159,8 @@ branch refs/heads/feature-relative
 
       const result = await resolver.findWorktreeForBranch('/Users/dev/project', 'feature-relative');
 
-      // Should resolve to absolute path
-      expect(result).toBe('/Users/dev/project/.worktrees/feature-relative');
+      // Should resolve to absolute path (platform-specific)
+      expect(result).toBe(normalizePath('/Users/dev/project/.worktrees/feature-relative'));
     });
 
     it('should use projectPath as cwd for git command', async () => {
@@ -186,17 +194,17 @@ branch refs/heads/feature-y
 
       expect(worktrees).toHaveLength(3);
       expect(worktrees[0]).toEqual({
-        path: '/Users/dev/project',
+        path: normalizePath('/Users/dev/project'),
         branch: 'main',
         isMain: true,
       });
       expect(worktrees[1]).toEqual({
-        path: '/Users/dev/project/.worktrees/feature-x',
+        path: normalizePath('/Users/dev/project/.worktrees/feature-x'),
         branch: 'feature-x',
         isMain: false,
       });
       expect(worktrees[2]).toEqual({
-        path: '/Users/dev/project/.worktrees/feature-y',
+        path: normalizePath('/Users/dev/project/.worktrees/feature-y'),
         branch: 'feature-y',
         isMain: false,
       });
@@ -226,7 +234,7 @@ detached
 
       expect(worktrees).toHaveLength(2);
       expect(worktrees[1]).toEqual({
-        path: '/Users/dev/project/.worktrees/detached-wt',
+        path: normalizePath('/Users/dev/project/.worktrees/detached-wt'),
         branch: null, // Detached HEAD has no branch
         isMain: false,
       });
@@ -264,7 +272,7 @@ branch refs/heads/relative-branch
 
       const worktrees = await resolver.listWorktrees('/Users/dev/project');
 
-      expect(worktrees[1].path).toBe('/Users/dev/project/.worktrees/relative-wt');
+      expect(worktrees[1].path).toBe(normalizePath('/Users/dev/project/.worktrees/relative-wt'));
     });
 
     it('should handle single worktree (main only)', async () => {
@@ -278,7 +286,7 @@ branch refs/heads/main
 
       expect(worktrees).toHaveLength(1);
       expect(worktrees[0]).toEqual({
-        path: '/Users/dev/project',
+        path: normalizePath('/Users/dev/project'),
         branch: 'main',
         isMain: true,
       });

apps/ui/scripts/prepare-server.mjs

@@ -7,8 +7,8 @@
  */
 
 import { execSync } from 'child_process';
-import { cpSync, existsSync, mkdirSync, rmSync, writeFileSync, readFileSync } from 'fs';
-import { join, dirname } from 'path';
+import { cpSync, existsSync, mkdirSync, rmSync, writeFileSync, readFileSync, lstatSync } from 'fs';
+import { join, dirname, resolve } from 'path';
 import { fileURLToPath } from 'url';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -112,6 +112,29 @@ execSync('npm install --omit=dev', {
   },
 });
 
+// Step 6b: Replace symlinks for local packages with real copies
+// npm install creates symlinks for file: references, but these break when packaged by electron-builder
+console.log('🔗 Replacing symlinks with real directory copies...');
+const nodeModulesAutomaker = join(BUNDLE_DIR, 'node_modules', '@automaker');
+for (const pkgName of LOCAL_PACKAGES) {
+  const pkgDir = pkgName.replace('@automaker/', '');
+  const nmPkgPath = join(nodeModulesAutomaker, pkgDir);
+  try {
+    // lstatSync does not follow symlinks, allowing us to check for broken ones
+    if (lstatSync(nmPkgPath).isSymbolicLink()) {
+      const realPath = resolve(BUNDLE_DIR, 'libs', pkgDir);
+      rmSync(nmPkgPath);
+      cpSync(realPath, nmPkgPath, { recursive: true });
+      console.log(`   ✓ Replaced symlink: ${pkgName}`);
+    }
+  } catch (error) {
+    // If the path doesn't exist, lstatSync throws ENOENT. We can safely ignore this.
+    if (error.code !== 'ENOENT') {
+      throw error;
+    }
+  }
+}
+
 // Step 7: Rebuild native modules for current architecture
 // This is critical for modules like node-pty that have native bindings
 console.log('🔨 Rebuilding native modules for current architecture...');

apps/ui/src/components/layout/project-switcher/project-switcher.tsx

@@ -1,7 +1,7 @@
 import { useState, useCallback, useEffect } from 'react';
 import { Plus, Bug, FolderOpen, BookOpen } from 'lucide-react';
 import { useNavigate, useLocation } from '@tanstack/react-router';
-import { cn } from '@/lib/utils';
+import { cn, isMac } from '@/lib/utils';
 import { useAppStore } from '@/store/app-store';
 import { useOSDetection } from '@/hooks/use-os-detection';
 import { ProjectSwitcherItem } from './components/project-switcher-item';
@@ -11,9 +11,12 @@ import { NotificationBell } from './components/notification-bell';
 import { NewProjectModal } from '@/components/dialogs/new-project-modal';
 import { OnboardingDialog } from '@/components/layout/sidebar/dialogs';
 import { useProjectCreation } from '@/components/layout/sidebar/hooks';
-import { SIDEBAR_FEATURE_FLAGS } from '@/components/layout/sidebar/constants';
+import {
+  MACOS_ELECTRON_TOP_PADDING_CLASS,
+  SIDEBAR_FEATURE_FLAGS,
+} from '@/components/layout/sidebar/constants';
 import type { Project } from '@/lib/electron';
-import { getElectronAPI } from '@/lib/electron';
+import { getElectronAPI, isElectron } from '@/lib/electron';
 import { initializeProject, hasAppSpec, hasAutomakerDir } from '@/lib/project-init';
 import { toast } from 'sonner';
 import { CreateSpecDialog } from '@/components/views/spec-view/dialogs';
@@ -279,7 +282,12 @@ export function ProjectSwitcher() {
         data-testid="project-switcher"
       >
         {/* Automaker Logo and Version */}
-        <div className="flex flex-col items-center pt-3 pb-2 px-2">
+        <div
+          className={cn(
+            'flex flex-col items-center pb-2 px-2',
+            isMac && isElectron() ? MACOS_ELECTRON_TOP_PADDING_CLASS : 'pt-3'
+          )}
+        >
           <button
             onClick={() => navigate({ to: '/dashboard' })}
             className="group flex flex-col items-center gap-0.5"

apps/ui/src/components/layout/sidebar/components/sidebar-header.tsx

@@ -6,6 +6,7 @@ import type { LucideIcon } from 'lucide-react';
 import { cn, isMac } from '@/lib/utils';
 import { formatShortcut } from '@/store/app-store';
 import { isElectron, type Project } from '@/lib/electron';
+import { MACOS_ELECTRON_TOP_PADDING_CLASS } from '../constants';
 import { getAuthenticatedImageUrl } from '@/lib/api-fetch';
 import { useAppStore } from '@/store/app-store';
 import {
@@ -89,7 +90,7 @@ export function SidebarHeader({
       <div
         className={cn(
           'shrink-0 flex flex-col items-center relative px-2 pt-3 pb-2',
-          isMac && isElectron() && 'pt-[10px]'
+          isMac && isElectron() && MACOS_ELECTRON_TOP_PADDING_CLASS
         )}
       >
         <Tooltip>
@@ -240,7 +241,7 @@ export function SidebarHeader({
     <div
       className={cn(
         'shrink-0 flex flex-col relative px-3 pt-3 pb-2',
-        isMac && isElectron() && 'pt-[10px]'
+        isMac && isElectron() && MACOS_ELECTRON_TOP_PADDING_CLASS
       )}
     >
       {/* Header with logo and project dropdown */}

apps/ui/src/components/layout/sidebar/components/sidebar-navigation.tsx

@@ -3,7 +3,9 @@ import type { NavigateOptions } from '@tanstack/react-router';
 import { ChevronDown, Wrench, Github, Folder } from 'lucide-react';
 import * as LucideIcons from 'lucide-react';
 import type { LucideIcon } from 'lucide-react';
-import { cn } from '@/lib/utils';
+import { cn, isMac } from '@/lib/utils';
+import { isElectron } from '@/lib/electron';
+import { MACOS_ELECTRON_TOP_PADDING_CLASS } from '../constants';
 import { formatShortcut, useAppStore } from '@/store/app-store';
 import { getAuthenticatedImageUrl } from '@/lib/api-fetch';
 import type { NavSection } from '../types';
@@ -117,7 +119,12 @@ export function SidebarNavigation({
       className={cn(
         'flex-1 overflow-y-auto scrollbar-hide px-3 pb-2',
         // Add top padding in discord mode since there's no header
-        sidebarStyle === 'discord' ? 'pt-3' : 'mt-1'
+        // Extra padding for macOS Electron to avoid traffic light overlap
+        sidebarStyle === 'discord'
+          ? isMac && isElectron()
+            ? MACOS_ELECTRON_TOP_PADDING_CLASS
+            : 'pt-3'
+          : 'mt-1'
       )}
     >
       {/* Project name display for classic/discord mode */}

apps/ui/src/components/layout/sidebar/constants.ts

@@ -1,5 +1,11 @@
 import { darkThemes, lightThemes } from '@/config/theme-options';
 
+/**
+ * Tailwind class for top padding on macOS Electron to avoid overlapping with traffic light window controls.
+ * This padding is applied conditionally when running on macOS in Electron.
+ */
+export const MACOS_ELECTRON_TOP_PADDING_CLASS = 'pt-[38px]';
+
 /**
  * Shared constants for theme submenu positioning and layout.
  * Used across project-context-menu and project-selector-with-options components

apps/ui/src/components/ui/provider-icon.tsx

@@ -116,9 +116,8 @@ const PROVIDER_ICON_DEFINITIONS: Record<ProviderIconKey, ProviderIconDefinition>
   },
   copilot: {
     viewBox: '0 0 98 96',
-    // Official GitHub Octocat logo mark
+    // Official GitHub Octocat logo mark (theme-aware via currentColor)
     path: 'M48.854 0C21.839 0 0 22 0 49.217c0 21.756 13.993 40.172 33.405 46.69 2.427.49 3.316-1.059 3.316-2.362 0-1.141-.08-5.052-.08-9.127-13.59 2.934-16.42-5.867-16.42-5.867-2.184-5.704-5.42-7.17-5.42-7.17-4.448-3.015.324-3.015.324-3.015 4.934.326 7.523 5.052 7.523 5.052 4.367 7.496 11.404 5.378 14.235 4.074.404-3.178 1.699-5.378 3.074-6.6-10.839-1.141-22.243-5.378-22.243-24.283 0-5.378 1.94-9.778 5.014-13.2-.485-1.222-2.184-6.275.486-13.038 0 0 4.125-1.304 13.426 5.052a46.97 46.97 0 0 1 12.214-1.63c4.125 0 8.33.571 12.213 1.63 9.302-6.356 13.427-5.052 13.427-5.052 2.67 6.763.97 11.816.485 13.038 3.155 3.422 5.015 7.822 5.015 13.2 0 18.905-11.404 23.06-22.324 24.283 1.78 1.548 3.316 4.481 3.316 9.126 0 6.6-.08 11.897-.08 13.526 0 1.304.89 2.853 3.316 2.364 19.412-6.52 33.405-24.935 33.405-46.691C97.707 22 75.788 0 48.854 0z',
-    fill: '#ffffff',
   },
 };
 

apps/ui/src/components/views/board-view.tsx

@@ -1275,8 +1275,10 @@ export function BoardView() {
         maxConcurrency={maxConcurrency}
         runningAgentsCount={runningAutoTasks.length}
         onConcurrencyChange={(newMaxConcurrency) => {
-          if (currentProject && selectedWorktree) {
-            const branchName = selectedWorktree.isMain ? null : selectedWorktree.branch;
+          if (currentProject) {
+            // If selectedWorktree is undefined or it's the main worktree, branchName will be null.
+            // Otherwise, use the branch name.
+            const branchName = selectedWorktree?.isMain === false ? selectedWorktree.branch : null;
             setMaxConcurrencyForWorktree(currentProject.id, branchName, newMaxConcurrency);
 
             // Persist to server settings so capacity checks use the correct value

libs/platform/src/system-paths.ts

@@ -750,6 +750,9 @@ export function electronUserDataWriteFileSync(
     throw new Error('[SystemPaths] Electron userData path not initialized');
   }
   const fullPath = path.join(electronUserDataPath, relativePath);
+  // Ensure parent directory exists (may not exist on first launch)
+  const dir = path.dirname(fullPath);
+  fsSync.mkdirSync(dir, { recursive: true });
   fsSync.writeFileSync(fullPath, data, options);
 }