fix(git): surface checkout failure details

Author: pallyoung

packages/server/src/__tests__/git/cli.test.ts

@@ -953,6 +953,32 @@ describe("runGitCheckout", () => {
     const { stdout } = await execFileAsync("git", ["branch", "--show-current"], { cwd: testDir });
     expect(stdout.trim()).toBe("feature/login-page");
   });
+
+  it("returns the underlying git error when checkout is blocked by another worktree", async () => {
+    await writeFile(join(testDir, "README.md"), "test");
+    await execFileAsync("git", ["add", "."], { cwd: testDir });
+    await execFileAsync("git", ["commit", "-m", "initial"], { cwd: testDir });
+
+    const linkedWorktreeDir = await mkdtemp(join(tmpdir(), "git-linked-worktree-"));
+    try {
+      await execFileAsync("git", ["branch", "feature/worktree-branch"], { cwd: testDir });
+      await execFileAsync(
+        "git",
+        ["worktree", "add", linkedWorktreeDir, "feature/worktree-branch"],
+        {
+          cwd: testDir,
+        }
+      );
+
+      const result = await runGitCheckout(testDir, "feature/worktree-branch");
+
+      expect(result.success).toBe(false);
+      expect(result.message).toContain("already used by worktree");
+      expect(result.message).toContain(linkedWorktreeDir);
+    } finally {
+      await rm(linkedWorktreeDir, { recursive: true, force: true });
+    }
+  });
 });
 
 describe("runGitPush", () => {

packages/server/src/git/cli.ts

@@ -551,6 +551,10 @@ export async function runGitCheckout(
   }
 ): Promise<{ success: boolean; message: string; branch?: string }> {
   const args = ["checkout"];
+  const formatCheckoutError = (error: unknown, fallbackMessage: string) =>
+    error instanceof GitError
+      ? error.stderr.trim() || error.message || fallbackMessage
+      : fallbackMessage;
 
   // Detect remote branch refs by querying actual configured remotes
   let isRemoteRef = false;
@@ -584,10 +588,10 @@ export async function runGitCheckout(
 
       // For remote branch checkout, we know the branch name from the ref
       return { success: true, message, branch: branchName };
-    } catch {
+    } catch (error) {
       return {
         success: false,
-        message: `Failed to checkout remote branch '${ref}'`,
+        message: formatCheckoutError(error, `Failed to checkout remote branch '${ref}'`),
       };
     }
   } else {
@@ -607,10 +611,10 @@ export async function runGitCheckout(
       const message = stdout || stderr || `Checkout to ${ref} completed`;
 
       return { success: true, message, branch };
-    } catch {
+    } catch (error) {
       return {
         success: false,
-        message: `Failed to checkout '${ref}'`,
+        message: formatCheckoutError(error, `Failed to checkout '${ref}'`),
       };
     }
   }