From 68cb3d17ae94066bb32cca2138c9a2a3945d8a28 Mon Sep 17 00:00:00 2001
From: Dotta <bippadotta@protonmail.com>
Date: Sun, 11 Oct 2026 07:59:23 -0500
Subject: [PATCH] Carry explicit existing-branch intent in workspace
 realization

Keep requested branch attachment separate from ownership established by realization, and round-trip the optional intent through the shared request contract.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
(cherry picked from commit ab1e8acc681154af651926e495e7a01b4d7715be)
---
 packages/shared/src/types/workspace-runtime.ts |  2 ++
 server/src/__tests__/workspace-runtime.test.ts | 13 +++++++++++++
 server/src/services/workspace-realization.ts   |  2 ++
 server/src/services/workspace-runtime.ts       |  2 ++
 4 files changed, 19 insertions(+)

diff --git a/packages/shared/src/types/workspace-runtime.ts b/packages/shared/src/types/workspace-runtime.ts
index 25a8dbf6549..479260c30c3 100644
--- a/packages/shared/src/types/workspace-runtime.ts
+++ b/packages/shared/src/types/workspace-runtime.ts
@@ -351,6 +351,8 @@ export interface WorkspaceRealizationRequest {
     repoRef: string | null;
     strategy: "project_primary" | "git_worktree";
     branchName: string | null;
+    /** Attach this exact pre-existing branch without creating or resetting it. */
+    existingBranch?: string;
     worktreePath: string | null;
   };
   /**
diff --git a/server/src/__tests__/workspace-runtime.test.ts b/server/src/__tests__/workspace-runtime.test.ts
index 021523b997b..7290a474b55 100644
--- a/server/src/__tests__/workspace-runtime.test.ts
+++ b/server/src/__tests__/workspace-runtime.test.ts
@@ -9444,6 +9444,19 @@ describe("workspace realization request additionalSources", () => {
     };
   }
 
+  it.each([undefined, "operator/retained"])("round-trips exact-branch intent independently of branch ownership (%s)", existingBranch => {
+    const workspace = buildRealizedWorkspace({ strategy: "git_worktree", branchName: existingBranch ?? "new-task-branch",
+      existingBranch, branchCreatedByRuntime: false });
+    const request = buildWorkspaceRealizationRequest({ adapterType: "codex", companyId: "company-1",
+      environmentId: "environment-1", executionWorkspaceId: null, issueId: "issue-1", heartbeatRunId: "run-1",
+      requestedMode: "isolated_workspace", workspace, workspaceConfig: null });
+    const parsed = readWorkspaceRealizationRequest(JSON.parse(JSON.stringify(request)));
+    expect(parsed?.source.existingBranch).toBe(existingBranch);
+    expect(parsed?.source.branchName).toBe(workspace.branchName);
+    expect(workspace.branchCreatedByRuntime).toBe(false);
+    if (!existingBranch) expect(request.source).not.toHaveProperty("existingBranch");
+  });
+
   it("round-trips additionalSources and runtime provisioning through build/read realization request", () => {
     const workspace = buildRealizedWorkspace({
       additionalWorkspaces: [
diff --git a/server/src/services/workspace-realization.ts b/server/src/services/workspace-realization.ts
index f69e393174e..3569611dc62 100644
--- a/server/src/services/workspace-realization.ts
+++ b/server/src/services/workspace-realization.ts
@@ -93,6 +93,7 @@ export function readWorkspaceRealizationRequest(value: unknown): WorkspaceRealiz
       repoRef: readString(source.repoRef),
       strategy: source.strategy === "git_worktree" ? "git_worktree" : "project_primary",
       branchName: readString(source.branchName),
+      ...(readString(source.existingBranch) ? { existingBranch: readString(source.existingBranch)! } : {}),
       worktreePath: readString(source.worktreePath),
     },
     additionalSources: readAdditionalSources(parsed.additionalSources),
@@ -137,6 +138,7 @@ export function buildWorkspaceRealizationRequest(input: {
       repoRef: input.workspace.repoRef,
       strategy: input.workspace.strategy,
       branchName: input.workspace.branchName,
+      ...(input.workspace.existingBranch ? { existingBranch: input.workspace.existingBranch } : {}),
       worktreePath: input.workspace.worktreePath,
     },
     // The additional (referenced) sources carry the read-only referenced-project workspaces. Run
diff --git a/server/src/services/workspace-runtime.ts b/server/src/services/workspace-runtime.ts
index 5c161536697..64989dfa452 100644
--- a/server/src/services/workspace-runtime.ts
+++ b/server/src/services/workspace-runtime.ts
@@ -170,6 +170,8 @@ export interface RealizedExecutionWorkspace extends ExecutionWorkspaceInput {
   strategy: "project_primary" | "git_worktree";
   cwd: string;
   branchName: string | null;
+  /** Remote realization intent; distinct from ownership established after creation. */
+  existingBranch?: string;
   worktreePath: string | null;
   warnings: string[];
   created: boolean;