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 ab1e8acc68)

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;
   };
   /**

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: [

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

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;