Redesign project codebase configuration

packages/shared/src/index.ts

@@ -108,6 +108,8 @@ export type {
   AdapterEnvironmentTestResult,
   AssetImage,
   Project,
+  ProjectCodebase,
+  ProjectCodebaseOrigin,
   ProjectGoalRef,
   ProjectWorkspace,
   ExecutionWorkspace,

packages/shared/src/types/index.ts

@@ -10,7 +10,7 @@ export type {
   AdapterEnvironmentTestResult,
 } from "./agent.js";
 export type { AssetImage } from "./asset.js";
-export type { Project, ProjectGoalRef, ProjectWorkspace } from "./project.js";
+export type { Project, ProjectCodebase, ProjectCodebaseOrigin, ProjectGoalRef, ProjectWorkspace } from "./project.js";
 export type {
   ExecutionWorkspace,
   WorkspaceRuntimeService,

packages/shared/src/types/project.ts

@@ -32,6 +32,20 @@ export interface ProjectWorkspace {
   updatedAt: Date;
 }
 
+export type ProjectCodebaseOrigin = "local_folder" | "managed_checkout";
+
+export interface ProjectCodebase {
+  workspaceId: string | null;
+  repoUrl: string | null;
+  repoRef: string | null;
+  defaultRef: string | null;
+  repoName: string | null;
+  localFolder: string | null;
+  managedFolder: string;
+  effectiveLocalFolder: string;
+  origin: ProjectCodebaseOrigin;
+}
+
 export interface Project {
   id: string;
   companyId: string;
@@ -47,6 +61,7 @@ export interface Project {
   targetDate: string | null;
   color: string | null;
   executionWorkspacePolicy: ProjectExecutionWorkspacePolicy | null;
+  codebase: ProjectCodebase;
   workspaces: ProjectWorkspace[];
   primaryWorkspace: ProjectWorkspace | null;
   archivedAt: Date | null;

server/src/home-paths.ts

@@ -4,6 +4,7 @@ import path from "node:path";
 const DEFAULT_INSTANCE_ID = "default";
 const INSTANCE_ID_RE = /^[a-zA-Z0-9_-]+$/;
 const PATH_SEGMENT_RE = /^[a-zA-Z0-9_-]+$/;
+const FRIENDLY_PATH_SEGMENT_RE = /[^a-zA-Z0-9._-]+/g;
 
 function expandHomePrefix(value: string): string {
   if (value === "~") return os.homedir();
@@ -61,6 +62,34 @@ export function resolveDefaultAgentWorkspaceDir(agentId: string): string {
   return path.resolve(resolvePaperclipInstanceRoot(), "workspaces", trimmed);
 }
 
+function sanitizeFriendlyPathSegment(value: string | null | undefined, fallback = "_default"): string {
+  const trimmed = value?.trim() ?? "";
+  if (!trimmed) return fallback;
+  const sanitized = trimmed
+    .replace(FRIENDLY_PATH_SEGMENT_RE, "-")
+    .replace(/^-+|-+$/g, "");
+  return sanitized || fallback;
+}
+
+export function resolveManagedProjectWorkspaceDir(input: {
+  companyId: string;
+  projectId: string;
+  repoName?: string | null;
+}): string {
+  const companyId = input.companyId.trim();
+  const projectId = input.projectId.trim();
+  if (!companyId || !projectId) {
+    throw new Error("Managed project workspace path requires companyId and projectId.");
+  }
+  return path.resolve(
+    resolvePaperclipInstanceRoot(),
+    "projects",
+    sanitizeFriendlyPathSegment(companyId, "company"),
+    sanitizeFriendlyPathSegment(projectId, "project"),
+    sanitizeFriendlyPathSegment(input.repoName, "_default"),
+  );
+}
+
 export function resolveHomeAwarePath(value: string): string {
   return path.resolve(expandHomePrefix(value));
 }

server/src/services/heartbeat.ts

@@ -1,5 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { execFile as execFileCallback } from "node:child_process";
+import { promisify } from "node:util";
 import { and, asc, desc, eq, gt, inArray, sql } from "drizzle-orm";
 import type { Db } from "@paperclipai/db";
 import {
@@ -23,7 +25,7 @@ import { createLocalAgentJwt } from "../agent-auth-jwt.js";
 import { parseObject, asBoolean, asNumber, appendWithCap, MAX_EXCERPT_BYTES } from "../adapters/utils.js";
 import { costService } from "./costs.js";
 import { secretService } from "./secrets.js";
-import { resolveDefaultAgentWorkspaceDir } from "../home-paths.js";
+import { resolveDefaultAgentWorkspaceDir, resolveManagedProjectWorkspaceDir } from "../home-paths.js";
 import { summarizeHeartbeatRunResultJson } from "./heartbeat-run-summary.js";
 import {
   buildWorkspaceReadyComment,
@@ -48,6 +50,7 @@ const HEARTBEAT_MAX_CONCURRENT_RUNS_MAX = 10;
 const DEFERRED_WAKE_CONTEXT_KEY = "_paperclipWakeContext";
 const startLocksByAgent = new Map<string, Promise<void>>();
 const REPO_ONLY_CWD_SENTINEL = "/__paperclip_repo_only__";
+const execFile = promisify(execFileCallback);
 const SESSIONED_LOCAL_ADAPTERS = new Set([
   "claude_local",
   "codex_local",
@@ -57,6 +60,69 @@ const SESSIONED_LOCAL_ADAPTERS = new Set([
   "pi_local",
 ]);
 
+function deriveRepoNameFromRepoUrl(repoUrl: string | null): string | null {
+  const trimmed = repoUrl?.trim() ?? "";
+  if (!trimmed) return null;
+  try {
+    const parsed = new URL(trimmed);
+    const cleanedPath = parsed.pathname.replace(/\/+$/, "");
+    const repoName = cleanedPath.split("/").filter(Boolean).pop()?.replace(/\.git$/i, "") ?? "";
+    return repoName || null;
+  } catch {
+    return null;
+  }
+}
+
+async function ensureManagedProjectWorkspace(input: {
+  companyId: string;
+  projectId: string;
+  repoUrl: string | null;
+}): Promise<{ cwd: string; warning: string | null }> {
+  const cwd = resolveManagedProjectWorkspaceDir({
+    companyId: input.companyId,
+    projectId: input.projectId,
+    repoName: deriveRepoNameFromRepoUrl(input.repoUrl),
+  });
+  await fs.mkdir(path.dirname(cwd), { recursive: true });
+  const stats = await fs.stat(cwd).catch(() => null);
+
+  if (!input.repoUrl) {
+    if (!stats) {
+      await fs.mkdir(cwd, { recursive: true });
+    }
+    return { cwd, warning: null };
+  }
+
+  const gitDirExists = await fs
+    .stat(path.resolve(cwd, ".git"))
+    .then((entry) => entry.isDirectory())
+    .catch(() => false);
+  if (gitDirExists) {
+    return { cwd, warning: null };
+  }
+
+  if (stats) {
+    const entries = await fs.readdir(cwd).catch(() => []);
+    if (entries.length > 0) {
+      return {
+        cwd,
+        warning: `Managed workspace path "${cwd}" already exists but is not a git checkout. Using it as-is.`,
+      };
+    }
+    await fs.rm(cwd, { recursive: true, force: true });
+  }
+
+  try {
+    await execFile("git", ["clone", input.repoUrl, cwd], {
+      env: process.env,
+    });
+    return { cwd, warning: null };
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to prepare managed checkout for "${input.repoUrl}" at "${cwd}": ${reason}`);
+  }
+}
+
 const heartbeatRunListColumns = {
   id: heartbeatRuns.id,
   companyId: heartbeatRuns.companyId,
@@ -876,12 +942,23 @@ export function heartbeatService(db: Db) {
           `Selected project workspace "${preferredProjectWorkspaceId}" is not available on this project.`;
       }
       for (const workspace of projectWorkspaceRows) {
-        const projectCwd = readNonEmptyString(workspace.cwd);
+        let projectCwd = readNonEmptyString(workspace.cwd);
+        let managedWorkspaceWarning: string | null = null;
         if (!projectCwd || projectCwd === REPO_ONLY_CWD_SENTINEL) {
-          if (preferredWorkspace?.id === workspace.id) {
-            preferredWorkspaceWarning = `Selected project workspace "${workspace.name}" has no local cwd configured.`;
+          try {
+            const managedWorkspace = await ensureManagedProjectWorkspace({
+              companyId: agent.companyId,
+              projectId: workspaceProjectId ?? resolvedProjectId ?? workspace.projectId,
+              repoUrl: readNonEmptyString(workspace.repoUrl),
+            });
+            projectCwd = managedWorkspace.cwd;
+            managedWorkspaceWarning = managedWorkspace.warning;
+          } catch (error) {
+            if (preferredWorkspace?.id === workspace.id) {
+              preferredWorkspaceWarning = error instanceof Error ? error.message : String(error);
+            }
+            continue;
           }
-          continue;
         }
         hasConfiguredProjectCwd = true;
         const projectCwdExists = await fs
@@ -897,7 +974,9 @@ export function heartbeatService(db: Db) {
             repoUrl: workspace.repoUrl,
             repoRef: workspace.repoRef,
             workspaceHints,
-            warnings: preferredWorkspaceWarning ? [preferredWorkspaceWarning] : [],
+            warnings: [preferredWorkspaceWarning, managedWorkspaceWarning].filter(
+              (value): value is string => Boolean(value),
+            ),
           };
         }
         if (preferredWorkspace?.id === workspace.id) {
@@ -938,6 +1017,24 @@ export function heartbeatService(db: Db) {
       };
     }
 
+    if (workspaceProjectId) {
+      const managedWorkspace = await ensureManagedProjectWorkspace({
+        companyId: agent.companyId,
+        projectId: workspaceProjectId,
+        repoUrl: null,
+      });
+      return {
+        cwd: managedWorkspace.cwd,
+        source: "project_primary" as const,
+        projectId: resolvedProjectId,
+        workspaceId: null,
+        repoUrl: null,
+        repoRef: null,
+        workspaceHints,
+        warnings: managedWorkspace.warning ? [managedWorkspace.warning] : [],
+      };
+    }
+
     const sessionCwd = readNonEmptyString(previousSessionParams?.cwd);
     if (sessionCwd) {
       const sessionCwdExists = await fs

server/src/services/plugin-host-services.ts

@@ -704,17 +704,16 @@ export function buildHostServices(
         const project = await projects.getById(params.projectId);
         if (!inCompany(project, companyId)) return null;
         const row = project.primaryWorkspace;
-        if (!row) return null;
-        const path = sanitizeWorkspacePath(row.cwd);
-        const name = sanitizeWorkspaceName(row.name, path);
+        const path = sanitizeWorkspacePath(project.codebase.effectiveLocalFolder);
+        const name = sanitizeWorkspaceName(row?.name ?? project.name, path);
         return {
-          id: row.id,
-          projectId: row.projectId,
+          id: row?.id ?? `${project.id}:managed`,
+          projectId: project.id,
           name,
           path,
-          isPrimary: row.isPrimary,
-          createdAt: row.createdAt.toISOString(),
-          updatedAt: row.updatedAt.toISOString(),
+          isPrimary: true,
+          createdAt: (row?.createdAt ?? project.createdAt).toISOString(),
+          updatedAt: (row?.updatedAt ?? project.updatedAt).toISOString(),
         };
       },
 
@@ -728,17 +727,16 @@ export function buildHostServices(
         const project = await projects.getById(projectId);
         if (!inCompany(project, companyId)) return null;
         const row = project.primaryWorkspace;
-        if (!row) return null;
-        const path = sanitizeWorkspacePath(row.cwd);
-        const name = sanitizeWorkspaceName(row.name, path);
+        const path = sanitizeWorkspacePath(project.codebase.effectiveLocalFolder);
+        const name = sanitizeWorkspaceName(row?.name ?? project.name, path);
         return {
-          id: row.id,
-          projectId: row.projectId,
+          id: row?.id ?? `${project.id}:managed`,
+          projectId: project.id,
           name,
           path,
-          isPrimary: row.isPrimary,
-          createdAt: row.createdAt.toISOString(),
-          updatedAt: row.updatedAt.toISOString(),
+          isPrimary: true,
+          createdAt: (row?.createdAt ?? project.createdAt).toISOString(),
+          updatedAt: (row?.updatedAt ?? project.updatedAt).toISOString(),
         };
       },
     },

server/src/services/projects.ts

@@ -6,6 +6,7 @@ import {
   deriveProjectUrlKey,
   isUuidLike,
   normalizeProjectUrlKey,
+  type ProjectCodebase,
   type ProjectExecutionWorkspacePolicy,
   type ProjectGoalRef,
   type ProjectWorkspace,
@@ -13,6 +14,7 @@ import {
 } from "@paperclipai/shared";
 import { listWorkspaceRuntimeServicesForProjectWorkspaces } from "./workspace-runtime.js";
 import { parseProjectExecutionWorkspacePolicy } from "./execution-workspace-policy.js";
+import { resolveManagedProjectWorkspaceDir } from "../home-paths.js";
 
 type ProjectRow = typeof projects.$inferSelect;
 type ProjectWorkspaceRow = typeof projectWorkspaces.$inferSelect;
@@ -41,6 +43,7 @@ interface ProjectWithGoals extends Omit<ProjectRow, "executionWorkspacePolicy">
   goalIds: string[];
   goals: ProjectGoalRef[];
   executionWorkspacePolicy: ProjectExecutionWorkspacePolicy | null;
+  codebase: ProjectCodebase;
   workspaces: ProjectWorkspace[];
   primaryWorkspace: ProjectWorkspace | null;
 }
@@ -135,7 +138,7 @@ function toWorkspace(
     projectId: row.projectId,
     name: row.name,
     sourceType: row.sourceType as ProjectWorkspace["sourceType"],
-    cwd: row.cwd,
+    cwd: normalizeWorkspaceCwd(row.cwd),
     repoUrl: row.repoUrl ?? null,
     repoRef: row.repoRef ?? null,
     defaultRef: row.defaultRef ?? row.repoRef ?? null,
@@ -153,6 +156,48 @@ function toWorkspace(
   };
 }
 
+function deriveRepoNameFromRepoUrl(repoUrl: string | null): string | null {
+  const raw = readNonEmptyString(repoUrl);
+  if (!raw) return null;
+  try {
+    const parsed = new URL(raw);
+    const cleanedPath = parsed.pathname.replace(/\/+$/, "");
+    const repoName = cleanedPath.split("/").filter(Boolean).pop()?.replace(/\.git$/i, "") ?? "";
+    return repoName || null;
+  } catch {
+    return null;
+  }
+}
+
+function deriveProjectCodebase(input: {
+  companyId: string;
+  projectId: string;
+  primaryWorkspace: ProjectWorkspace | null;
+  fallbackWorkspaces: ProjectWorkspace[];
+}): ProjectCodebase {
+  const primaryWorkspace = input.primaryWorkspace ?? input.fallbackWorkspaces[0] ?? null;
+  const repoUrl = primaryWorkspace?.repoUrl ?? null;
+  const repoName = deriveRepoNameFromRepoUrl(repoUrl);
+  const localFolder = primaryWorkspace?.cwd ?? null;
+  const managedFolder = resolveManagedProjectWorkspaceDir({
+    companyId: input.companyId,
+    projectId: input.projectId,
+    repoName,
+  });
+
+  return {
+    workspaceId: primaryWorkspace?.id ?? null,
+    repoUrl,
+    repoRef: primaryWorkspace?.repoRef ?? null,
+    defaultRef: primaryWorkspace?.defaultRef ?? null,
+    repoName,
+    localFolder,
+    managedFolder,
+    effectiveLocalFolder: localFolder ?? managedFolder,
+    origin: localFolder ? "local_folder" : "managed_checkout",
+  };
+}
+
 function pickPrimaryWorkspace(
   rows: ProjectWorkspaceRow[],
   runtimeServicesByWorkspaceId?: Map<string, WorkspaceRuntimeService[]>,
@@ -203,10 +248,17 @@ async function attachWorkspaces(db: Db, rows: ProjectWithGoals[]): Promise<Proje
         sharedRuntimeServicesByWorkspaceId.get(workspace.id) ?? [],
       ),
     );
+    const primaryWorkspace = pickPrimaryWorkspace(projectWorkspaceRows, sharedRuntimeServicesByWorkspaceId);
     return {
       ...row,
+      codebase: deriveProjectCodebase({
+        companyId: row.companyId,
+        projectId: row.id,
+        primaryWorkspace,
+        fallbackWorkspaces: workspaces,
+      }),
       workspaces,
-      primaryWorkspace: pickPrimaryWorkspace(projectWorkspaceRows, sharedRuntimeServicesByWorkspaceId),
+      primaryWorkspace,
     };
   });
 }

ui/src/components/NewProjectDialog.tsx

@@ -42,7 +42,6 @@ const projectStatuses = [
 ];
 
 type WorkspaceSetup = "none" | "local" | "repo" | "both";
-const REPO_ONLY_CWD_SENTINEL = "/__paperclip_repo_only__";
 
 export function NewProjectDialog() {
   const { newProjectOpen, closeNewProject } = useDialog();
@@ -142,7 +141,7 @@ export function NewProjectDialog() {
       return;
     }
     if (repoRequired && !isGitHubRepoUrl(repoUrl)) {
-      setWorkspaceError("Repo workspace must use a valid GitHub repo URL.");
+      setWorkspaceError("Repo must use a valid GitHub repo URL.");
       return;
     }
 
@@ -173,7 +172,6 @@ export function NewProjectDialog() {
       } else if (repoRequired) {
         workspacePayloads.push({
           name: deriveWorkspaceNameFromRepo(repoUrl),
-          cwd: REPO_ONLY_CWD_SENTINEL,
           repoUrl,
         });
       }
@@ -284,7 +282,7 @@ export function NewProjectDialog() {
         <div className="px-4 pb-3 space-y-3 border-t border-border">
           <div className="pt-3">
             <p className="text-sm font-medium">Where will work be done on this project?</p>
-            <p className="text-xs text-muted-foreground">Add local folder and/or GitHub repo workspace hints.</p>
+            <p className="text-xs text-muted-foreground">Add a repo and/or local folder for this project.</p>
           </div>
           <div className="grid gap-2 sm:grid-cols-3">
             <button
@@ -311,7 +309,7 @@ export function NewProjectDialog() {
             >
               <div className="flex items-center gap-2 text-sm font-medium">
                 <Github className="h-4 w-4" />
-                A github repo
+                A repo
               </div>
               <p className="mt-1 text-xs text-muted-foreground">Paste a GitHub URL.</p>
             </button>
@@ -327,7 +325,7 @@ export function NewProjectDialog() {
                 <GitBranch className="h-4 w-4" />
                 Both
               </div>
-              <p className="mt-1 text-xs text-muted-foreground">Configure local + repo hints.</p>
+              <p className="mt-1 text-xs text-muted-foreground">Configure both repo and local folder.</p>
             </button>
           </div>
 
@@ -347,7 +345,7 @@ export function NewProjectDialog() {
           )}
           {(workspaceSetup === "repo" || workspaceSetup === "both") && (
             <div className="rounded-md border border-border p-2">
-              <label className="mb-1 block text-xs text-muted-foreground">GitHub repo URL</label>
+              <label className="mb-1 block text-xs text-muted-foreground">Repo URL</label>
               <input
                 className="w-full rounded border border-border bg-transparent px-2 py-1 text-xs outline-none"
                 value={workspaceRepoUrl}

ui/src/components/ProjectProperties.tsx

@@ -48,8 +48,6 @@ export type ProjectConfigFieldKey =
   | "execution_workspace_provision_command"
   | "execution_workspace_teardown_command";
 
-const REPO_ONLY_CWD_SENTINEL = "/__paperclip_repo_only__";
-
 function SaveIndicator({ state }: { state: ProjectFieldSaveState }) {
   if (state === "saving") {
     return (
@@ -191,6 +189,9 @@ export function ProjectProperties({ project, onUpdate, onFieldUpdate, getFieldSa
 
   const availableGoals = (allGoals ?? []).filter((g) => !linkedGoalIds.includes(g.id));
   const workspaces = project.workspaces ?? [];
+  const codebase = project.codebase;
+  const primaryCodebaseWorkspace = project.primaryWorkspace ?? null;
+  const hasAdditionalLegacyWorkspaces = workspaces.some((workspace) => workspace.id !== primaryCodebaseWorkspace?.id);
   const executionWorkspacePolicy = project.executionWorkspacePolicy ?? null;
   const executionWorkspacesEnabled = executionWorkspacePolicy?.enabled === true;
   const executionWorkspaceDefaultMode =
@@ -268,37 +269,51 @@ export function ProjectProperties({ project, onUpdate, onFieldUpdate, getFieldSa
     }
   };
 
-  const deriveWorkspaceNameFromPath = (value: string) => {
-    const normalized = value.trim().replace(/[\\/]+$/, "");
-    const segments = normalized.split(/[\\/]/).filter(Boolean);
-    return segments[segments.length - 1] ?? "Local folder";
-  };
-
-  const deriveWorkspaceNameFromRepo = (value: string) => {
+  const formatRepoUrl = (value: string) => {
     try {
       const parsed = new URL(value);
       const segments = parsed.pathname.split("/").filter(Boolean);
-      const repo = segments[segments.length - 1]?.replace(/\.git$/i, "") ?? "";
-      return repo || "GitHub repo";
-    } catch {
-      return "GitHub repo";
-    }
-  };
-
-  const formatGitHubRepo = (value: string) => {
-    try {
-      const parsed = new URL(value);
-      const segments = parsed.pathname.split("/").filter(Boolean);
-      if (segments.length < 2) return value;
+      if (segments.length < 2) return parsed.host;
       const owner = segments[0];
       const repo = segments[1]?.replace(/\.git$/i, "");
-      if (!owner || !repo) return value;
-      return `${owner}/${repo}`;
+      if (!owner || !repo) return parsed.host;
+      return `${parsed.host}/${owner}/${repo}`;
     } catch {
       return value;
     }
   };
 
+  const deriveSourceType = (cwd: string | null, repoUrl: string | null) => {
+    if (repoUrl) return "git_repo";
+    if (cwd) return "local_path";
+    return undefined;
+  };
+
+  const persistCodebase = (patch: { cwd?: string | null; repoUrl?: string | null }) => {
+    const nextCwd = patch.cwd !== undefined ? patch.cwd : codebase.localFolder;
+    const nextRepoUrl = patch.repoUrl !== undefined ? patch.repoUrl : codebase.repoUrl;
+    if (!nextCwd && !nextRepoUrl) {
+      if (primaryCodebaseWorkspace) {
+        removeWorkspace.mutate(primaryCodebaseWorkspace.id);
+      }
+      return;
+    }
+
+    const data: Record<string, unknown> = {
+      ...(patch.cwd !== undefined ? { cwd: patch.cwd } : {}),
+      ...(patch.repoUrl !== undefined ? { repoUrl: patch.repoUrl } : {}),
+      ...(deriveSourceType(nextCwd, nextRepoUrl) ? { sourceType: deriveSourceType(nextCwd, nextRepoUrl) } : {}),
+      isPrimary: true,
+    };
+
+    if (primaryCodebaseWorkspace) {
+      updateWorkspace.mutate({ workspaceId: primaryCodebaseWorkspace.id, data });
+      return;
+    }
+
+    createWorkspace.mutate(data);
+  };
+
   const submitLocalWorkspace = () => {
     const cwd = workspaceCwd.trim();
     if (!isAbsolutePath(cwd)) {
@@ -306,59 +321,45 @@ export function ProjectProperties({ project, onUpdate, onFieldUpdate, getFieldSa
       return;
     }
     setWorkspaceError(null);
-    createWorkspace.mutate({
-      name: deriveWorkspaceNameFromPath(cwd),
-      cwd,
-    });
+    persistCodebase({ cwd });
   };
 
   const submitRepoWorkspace = () => {
     const repoUrl = workspaceRepoUrl.trim();
     if (!isGitHubRepoUrl(repoUrl)) {
-      setWorkspaceError("Repo workspace must use a valid GitHub repo URL.");
+      setWorkspaceError("Repo must use a valid GitHub repo URL.");
       return;
     }
     setWorkspaceError(null);
-    createWorkspace.mutate({
-      name: deriveWorkspaceNameFromRepo(repoUrl),
-      cwd: REPO_ONLY_CWD_SENTINEL,
-      repoUrl,
-    });
+    persistCodebase({ repoUrl });
   };
 
-  const clearLocalWorkspace = (workspace: Project["workspaces"][number]) => {
+  const clearLocalWorkspace = () => {
     const confirmed = window.confirm(
-      workspace.repoUrl
+      codebase.repoUrl
         ? "Clear local folder from this workspace?"
         : "Delete this workspace local folder?",
     );
     if (!confirmed) return;
-    if (workspace.repoUrl) {
-      updateWorkspace.mutate({
-        workspaceId: workspace.id,
-        data: { cwd: null },
-      });
-      return;
-    }
-    removeWorkspace.mutate(workspace.id);
+    persistCodebase({ cwd: null });
   };
 
-  const clearRepoWorkspace = (workspace: Project["workspaces"][number]) => {
-    const hasLocalFolder = Boolean(workspace.cwd && workspace.cwd !== REPO_ONLY_CWD_SENTINEL);
+  const clearRepoWorkspace = () => {
+    const hasLocalFolder = Boolean(codebase.localFolder);
     const confirmed = window.confirm(
       hasLocalFolder
-        ? "Clear GitHub repo from this workspace?"
+        ? "Clear repo from this workspace?"
         : "Delete this workspace repo?",
     );
     if (!confirmed) return;
-    if (hasLocalFolder) {
+    if (primaryCodebaseWorkspace) {
       updateWorkspace.mutate({
-        workspaceId: workspace.id,
-        data: { repoUrl: null, repoRef: null },
+        workspaceId: primaryCodebaseWorkspace.id,
+        data: { repoUrl: null, repoRef: null, defaultRef: null, sourceType: deriveSourceType(codebase.localFolder, null) },
       });
       return;
     }
-    removeWorkspace.mutate(workspace.id);
+    persistCodebase({ repoUrl: null });
   };
 
   return (
@@ -494,114 +495,133 @@ export function ProjectProperties({ project, onUpdate, onFieldUpdate, getFieldSa
       <div className="space-y-1 py-4">
         <div className="space-y-2">
           <div className="flex items-center gap-1.5 text-xs text-muted-foreground">
-            <span>Workspaces</span>
+            <span>Codebase</span>
             <Tooltip>
               <TooltipTrigger asChild>
                 <button
                   type="button"
                   className="inline-flex h-4 w-4 items-center justify-center rounded-full border border-border text-[10px] text-muted-foreground hover:text-foreground"
-                  aria-label="Workspaces help"
+                  aria-label="Codebase help"
                 >
                   ?
                 </button>
               </TooltipTrigger>
               <TooltipContent side="top">
-                Workspaces give your agents hints about where the work is
+                Repo identifies the source of truth. Local folder is the default place agents write code.
               </TooltipContent>
             </Tooltip>
           </div>
-          {workspaces.length === 0 ? (
-            <p className="rounded-md border border-dashed border-border px-3 py-2 text-sm text-muted-foreground">
-              No workspace configured.
-            </p>
-          ) : (
+          <div className="space-y-2 rounded-md border border-border/70 p-3">
             <div className="space-y-1">
-              {workspaces.map((workspace) => (
-                <div key={workspace.id} className="space-y-1">
-                  {workspace.cwd && workspace.cwd !== REPO_ONLY_CWD_SENTINEL ? (
-                    <div className="flex items-center justify-between gap-2 py-1">
-                      <span className="min-w-0 truncate font-mono text-xs text-muted-foreground">{workspace.cwd}</span>
-                      <Button
-                        variant="ghost"
-                        size="icon-xs"
-                        onClick={() => clearLocalWorkspace(workspace)}
-                        aria-label="Delete local folder"
-                      >
-                        <Trash2 className="h-3 w-3" />
-                      </Button>
-                    </div>
-                  ) : null}
-                  {workspace.repoUrl ? (
-                    <div className="flex items-center justify-between gap-2 py-1">
-                      <a
-                        href={workspace.repoUrl}
-                        target="_blank"
-                        rel="noreferrer"
-                        className="inline-flex min-w-0 items-center gap-1.5 text-xs text-muted-foreground hover:text-foreground hover:underline"
-                      >
-                        <Github className="h-3 w-3 shrink-0" />
-                        <span className="truncate">{formatGitHubRepo(workspace.repoUrl)}</span>
-                        <ExternalLink className="h-3 w-3 shrink-0" />
-                      </a>
-                      <Button
-                        variant="ghost"
-                        size="icon-xs"
-                        onClick={() => clearRepoWorkspace(workspace)}
-                        aria-label="Delete workspace repo"
-                      >
-                        <Trash2 className="h-3 w-3" />
-                      </Button>
-                    </div>
-                  ) : null}
-                  {workspace.runtimeServices && workspace.runtimeServices.length > 0 ? (
-                    <div className="space-y-1 pl-2">
-                      {workspace.runtimeServices.map((service) => (
-                        <div
-                          key={service.id}
-                          className="flex items-center justify-between gap-2 rounded-md border border-border/60 px-2 py-1"
-                        >
-                          <div className="min-w-0 space-y-0.5">
-                            <div className="flex items-center gap-2">
-                              <span className="text-[11px] font-medium">{service.serviceName}</span>
-                              <span
-                                className={cn(
-                                  "rounded-full px-1.5 py-0.5 text-[10px] uppercase tracking-wide",
-                                  service.status === "running"
-                                    ? "bg-green-500/15 text-green-700 dark:text-green-300"
-                                    : service.status === "failed"
-                                      ? "bg-red-500/15 text-red-700 dark:text-red-300"
-                                      : "bg-muted text-muted-foreground",
-                                )}
-                              >
-                                {service.status}
-                              </span>
-                            </div>
-                            <div className="text-[11px] text-muted-foreground">
-                              {service.url ? (
-                                <a
-                                  href={service.url}
-                                  target="_blank"
-                                  rel="noreferrer"
-                                  className="hover:text-foreground hover:underline"
-                                >
-                                  {service.url}
-                                </a>
-                              ) : (
-                                service.command ?? "No URL"
-                              )}
-                            </div>
-                          </div>
-                          <div className="text-[10px] text-muted-foreground whitespace-nowrap">
-                            {service.lifecycle}
-                          </div>
-                        </div>
-                      ))}
-                    </div>
-                  ) : null}
+              <div className="text-[11px] uppercase tracking-wide text-muted-foreground">Repo</div>
+              {codebase.repoUrl ? (
+                <div className="flex items-center justify-between gap-2">
+                  <a
+                    href={codebase.repoUrl}
+                    target="_blank"
+                    rel="noreferrer"
+                    className="inline-flex min-w-0 items-center gap-1.5 text-xs text-muted-foreground hover:text-foreground hover:underline"
+                  >
+                    <Github className="h-3 w-3 shrink-0" />
+                    <span className="truncate">{formatRepoUrl(codebase.repoUrl)}</span>
+                    <ExternalLink className="h-3 w-3 shrink-0" />
+                  </a>
+                  <Button
+                    variant="ghost"
+                    size="icon-xs"
+                    onClick={clearRepoWorkspace}
+                    aria-label="Clear repo"
+                  >
+                    <Trash2 className="h-3 w-3" />
+                  </Button>
                 </div>
-              ))}
+              ) : (
+                <div className="text-xs text-muted-foreground">Not set.</div>
+              )}
             </div>
-          )}
+
+            <div className="space-y-1">
+              <div className="text-[11px] uppercase tracking-wide text-muted-foreground">Local folder</div>
+              {codebase.localFolder ? (
+                <div className="flex items-center justify-between gap-2">
+                  <span className="min-w-0 truncate font-mono text-xs text-muted-foreground">{codebase.localFolder}</span>
+                  <Button
+                    variant="ghost"
+                    size="icon-xs"
+                    onClick={clearLocalWorkspace}
+                    aria-label="Clear local folder"
+                  >
+                    <Trash2 className="h-3 w-3" />
+                  </Button>
+                </div>
+              ) : (
+                <div className="space-y-1">
+                  <div className="text-xs text-muted-foreground">Not set.</div>
+                  <div className="text-[11px] text-muted-foreground">Paperclip will use a managed checkout instead.</div>
+                </div>
+              )}
+            </div>
+
+            <div className="rounded-md border border-border/60 bg-muted/20 px-2.5 py-2">
+              <div className="text-[11px] uppercase tracking-wide text-muted-foreground">Effective working folder</div>
+              <div className="mt-1 break-all font-mono text-xs text-foreground">{codebase.effectiveLocalFolder}</div>
+              <div className="mt-1 text-[11px] text-muted-foreground">
+                {codebase.origin === "local_folder" ? "Using your local folder." : "Paperclip-managed folder."}
+              </div>
+            </div>
+
+            {hasAdditionalLegacyWorkspaces && (
+              <div className="text-[11px] text-muted-foreground">
+                Additional legacy workspace records exist on this project. Paperclip is using the primary workspace as the codebase view.
+              </div>
+            )}
+
+            {primaryCodebaseWorkspace?.runtimeServices && primaryCodebaseWorkspace.runtimeServices.length > 0 ? (
+              <div className="space-y-1">
+                {primaryCodebaseWorkspace.runtimeServices.map((service) => (
+                  <div
+                    key={service.id}
+                    className="flex items-center justify-between gap-2 rounded-md border border-border/60 px-2 py-1"
+                  >
+                    <div className="min-w-0 space-y-0.5">
+                      <div className="flex items-center gap-2">
+                        <span className="text-[11px] font-medium">{service.serviceName}</span>
+                        <span
+                          className={cn(
+                            "rounded-full px-1.5 py-0.5 text-[10px] uppercase tracking-wide",
+                            service.status === "running"
+                              ? "bg-green-500/15 text-green-700 dark:text-green-300"
+                              : service.status === "failed"
+                                ? "bg-red-500/15 text-red-700 dark:text-red-300"
+                                : "bg-muted text-muted-foreground",
+                          )}
+                        >
+                          {service.status}
+                        </span>
+                      </div>
+                      <div className="text-[11px] text-muted-foreground">
+                        {service.url ? (
+                          <a
+                            href={service.url}
+                            target="_blank"
+                            rel="noreferrer"
+                            className="hover:text-foreground hover:underline"
+                          >
+                            {service.url}
+                          </a>
+                        ) : (
+                          service.command ?? "No URL"
+                        )}
+                      </div>
+                    </div>
+                    <div className="text-[10px] text-muted-foreground whitespace-nowrap">
+                      {service.lifecycle}
+                    </div>
+                  </div>
+                ))}
+              </div>
+            ) : null}
+          </div>
           <div className="flex flex-col items-start gap-2">
             <Button
               variant="outline"
@@ -609,10 +629,11 @@ export function ProjectProperties({ project, onUpdate, onFieldUpdate, getFieldSa
               className="h-7 px-2.5"
               onClick={() => {
                 setWorkspaceMode("local");
+                setWorkspaceCwd(codebase.localFolder ?? "");
                 setWorkspaceError(null);
               }}
             >
-              Add workspace local folder
+              {codebase.localFolder ? "Change local folder" : "Set local folder"}
             </Button>
             <Button
               variant="outline"
@@ -620,10 +641,11 @@ export function ProjectProperties({ project, onUpdate, onFieldUpdate, getFieldSa
               className="h-7 px-2.5"
               onClick={() => {
                 setWorkspaceMode("repo");
+                setWorkspaceRepoUrl(codebase.repoUrl ?? "");
                 setWorkspaceError(null);
               }}
             >
-              Add workspace repo
+              {codebase.repoUrl ? "Change repo" : "Set repo"}
             </Button>
           </div>
           {workspaceMode === "local" && (