refactor(projects): identify projects by DB projectId instead of folder-derived name

GET /api/projects used to scan ~/.claude/projects/ on every request, derive
each project's identity from the encoded folder name, and re-parse JSONL
files to build session lists. Using the folder-derived name as the project
identifier leaked the Claude CLI's on-disk encoding into every API route,
forced every downstream endpoint to re-resolve a real path via JSONL
'cwd' inspection, and made the project list endpoint O(projects x sessions)
on disk I/O.

This change switches the entire API surface to identify projects by the
stable primary key from the 'projects' table and drives the listing
straight from the DB:

- Add projectsDb.getProjectPathById as the canonical projectId -> path
  resolver so routes no longer need to touch the filesystem to figure out
  where a project lives.

- Rewrite getProjects so it reads the project list from the 'projects'
  table and the per-project session list from the 'sessions' table (one
  SELECT per project). No filesystem scanning happens for this endpoint
  anymore, which removes the dependency on ~/.claude/projects existing,
  on Cursor's MD5-hashed chat folders being discoverable, and on Codex's
  JSONL history being on disk. Per the migration spec each session now
  exposes 'summary' sourced from sessions.custom_name, 'messageCount' = 0
  (message counting is not implemented), and sessionMeta.hasMore is
  pinned to false since this endpoint doesn't drive session pagination.

- Introduce id-based wrappers (getSessionsById, renameProjectById,
  deleteSessionById, deleteProjectById, getProjectTaskMasterById) so
  every caller can pass projectId and resolve the real path through the
  DB. renameProjectById also writes to projects.custom_project_name so
  the DB-driven getProjects response reflects renames immediately; it
  keeps project-config.json in sync for any legacy reader that still
  consults the JSON file.

- Migrate every /api/projects/:projectName route in server/index.js,
  server/routes/taskmaster.js, and server/routes/messages.js to
  :projectId, and change server/routes/git.js so the 'project'
  query/body parameter carries a projectId that is resolved through the
  DB before any git command runs. TaskMaster WebSocket broadcasts emit
  'projectId' for the same reason so the frontend can match
  notifications against its current selection without another lookup.

- Delete helpers that existed only to feed the old getProjects path
  (getCursorSessions, getGeminiCliSessions, getProjectTaskMaster) along
  with their unused imports (better-sqlite3's Database,
  applyCustomSessionNames). The legacy folder-name helpers (getSessions,
  renameProject, deleteSession, deleteProject, extractProjectDirectory)
  are kept as internal implementation details of the id-based wrappers
  and of destructive cleanup / conversation search, but they are no
  longer re-exported.

- searchConversations still walks JSONL to produce match snippets (that
  data doesn't live in the DB), but it now includes the resolved
  projectId in each result so the sidebar can cross-reference hits with
  its already loaded project list without a second round-trip.

Frontend migration:

- Project.name is replaced by Project.projectId in src/types/app.ts, and
  ProjectSession.__projectName becomes __projectId so session tagging
  and sidebar state keys stay aligned with the backend identifier.
  Settings continues to use SettingsProject.name for legacy consumers,
  but it is populated from projectId by normalizeProjectForSettings.

- All places that previously indexed per-project state by project.name
  (sidebar expanded/starred/loading/deletingProjects sets,
  additionalSessions map, projectHasMoreOverrides, starredProjects
  localStorage, command history and draft-input localStorage,
  TaskMaster caches) now key on projectId so state survives
  display-name edits and is consistent across the app.

- src/utils/api.js renames every endpoint parameter to projectId, the
  unified messages endpoint takes projectId in its query string, and
  useSessionStore forwards projectId on fetchFromServer / fetchMore /
  refreshFromServer. Git panel, file tree, code editor, PRD editor,
  plugins context, MCP server flows and TaskMaster hooks are all
  updated to pass projectId.

- DEFAULT_PROJECT_FOR_EMPTY_SHELL is updated to carry a 'default'
  projectId sentinel so the empty-shell placeholder still satisfies the
  Project contract.

Bug fix bundled in:

- sessionsDb.setName no longer bumps updated_at when a row already
  exists. Renaming is a label change, not activity, so there is no
  reason for it to reset 'last activity' in the sidebar. It also no
  longer relies on SQLite's CURRENT_TIMESTAMP, which stores a naive
  'YYYY-MM-DD HH:MM:SS' value that JavaScript parses as local time and
  caused renamed sessions to appear shifted backwards by the client's
  UTC offset. When an INSERT actually happens it now writes ISO-8601
  UTC with a 'Z' suffix.

- buildSessionsByProviderFromDb normalizes any legacy naive timestamps
  in the sessions table to ISO-8601 UTC on the way out so rows written
  before this change also render correctly on the client.

Other cleanup:

- Removed the filesystem-first project-discovery comment block at the
  top of server/projects.js and replaced it with a short note that
  describes the new DB-driven flow and lists the few remaining
  filesystem-dependent helpers (message reads, search, destructive
  delete, manual project registration).

- server/modules/providers/index.ts is added as a small barrel so the
  providers module exposes a stable public surface.

Made-with: Cursor

src/components/sidebar/hooks/useSidebarController.ts

@@ -42,6 +42,9 @@ type ConversationSession = {
 };
 
 type ConversationProjectResult = {
+  // Emitted by server/projects.js#searchConversations so the sidebar can map a
+  // match back to the Project in its current state by projectId.
+  projectId: string | null;
   projectName: string;
   projectDisplayName: string;
   sessions: ConversationSession[];
@@ -69,7 +72,8 @@ type UseSidebarControllerArgs = {
   onProjectSelect: (project: Project) => void;
   onSessionSelect: (session: ProjectSession) => void;
   onSessionDelete?: (sessionId: string) => void;
-  onProjectDelete?: (projectName: string) => void;
+  // `projectId` is the DB-assigned identifier; callbacks use that post-migration.
+  onProjectDelete?: (projectId: string) => void;
   setCurrentProject: (project: Project) => void;
   setSidebarVisible: (visible: boolean) => void;
   sidebarVisible: boolean;
@@ -135,13 +139,15 @@ export function useSidebarController({
   }, [projects]);
 
   useEffect(() => {
+    // Expanded-project tracking is now keyed by the DB `projectId` so state
+    // survives display-name edits and other mutations.
     if (selectedProject) {
       setExpandedProjects((prev) => {
-        if (prev.has(selectedProject.name)) {
+        if (prev.has(selectedProject.projectId)) {
           return prev;
         }
         const next = new Set(prev);
-        next.add(selectedProject.name);
+        next.add(selectedProject.projectId);
         return next;
       });
     }
@@ -152,7 +158,7 @@ export function useSidebarController({
       const loadedProjects = new Set<string>();
       projects.forEach((project) => {
         if (project.sessions && project.sessions.length >= 0) {
-          loadedProjects.add(project.name);
+          loadedProjects.add(project.projectId);
         }
       });
       setInitialSessionsLoaded(loadedProjects);
@@ -296,30 +302,34 @@ export function useSidebarController({
     [],
   );
 
-  const toggleProject = useCallback((projectName: string) => {
+  // All sidebar state keys (expanded, starred, loading, etc.) use the DB
+  // `projectId` as their identifier after the migration.
+  const toggleProject = useCallback((projectId: string) => {
     setExpandedProjects((prev) => {
       const next = new Set<string>();
-      if (!prev.has(projectName)) {
-        next.add(projectName);
+      if (!prev.has(projectId)) {
+        next.add(projectId);
       }
       return next;
     });
   }, []);
 
   const handleSessionClick = useCallback(
-    (session: SessionWithProvider, projectName: string) => {
-      onSessionSelect({ ...session, __projectName: projectName });
+    (session: SessionWithProvider, projectId: string) => {
+      // Tag the session with its owning projectId so downstream handlers
+      // can correlate it with the selectedProject in the app state.
+      onSessionSelect({ ...session, __projectId: projectId });
     },
     [onSessionSelect],
   );
 
-  const toggleStarProject = useCallback((projectName: string) => {
+  const toggleStarProject = useCallback((projectId: string) => {
     setStarredProjects((prev) => {
       const next = new Set(prev);
-      if (next.has(projectName)) {
-        next.delete(projectName);
+      if (next.has(projectId)) {
+        next.delete(projectId);
       } else {
-        next.add(projectName);
+        next.add(projectId);
       }
 
       persistStarredProjects(next);
@@ -328,7 +338,7 @@ export function useSidebarController({
   }, []);
 
   const isProjectStarred = useCallback(
-    (projectName: string) => starredProjects.has(projectName),
+    (projectId: string) => starredProjects.has(projectId),
     [starredProjects],
   );
 
@@ -340,7 +350,8 @@ export function useSidebarController({
   const projectsWithSessionMeta = useMemo(
     () =>
       projects.map((project) => {
-        const hasMoreOverride = projectHasMoreOverrides[project.name];
+        // The `hasMore` override map is keyed by projectId (see loadMoreSessions).
+        const hasMoreOverride = projectHasMoreOverrides[project.projectId];
         if (hasMoreOverride === undefined) {
           return project;
         }
@@ -364,7 +375,9 @@ export function useSidebarController({
   );
 
   const startEditing = useCallback((project: Project) => {
-    setEditingProject(project.name);
+    // `editingProject` is keyed by projectId so it stays stable across
+    // display-name mutations that happen while the input is open.
+    setEditingProject(project.projectId);
     setEditingName(project.displayName);
   }, []);
 
@@ -374,9 +387,11 @@ export function useSidebarController({
   }, []);
 
   const saveProjectName = useCallback(
-    async (projectName: string) => {
+    // `projectId` is the DB primary key; the rename API resolves the path
+    // through the `projects` table before writing the new display name.
+    async (projectId: string) => {
       try {
-        const response = await api.renameProject(projectName, editingName);
+        const response = await api.renameProject(projectId, editingName);
         if (response.ok) {
           if (window.refreshProjects) {
             await window.refreshProjects();
@@ -397,13 +412,15 @@ export function useSidebarController({
   );
 
   const showDeleteSessionConfirmation = useCallback(
+    // `projectId` (not the legacy folder-encoded name) is what the DELETE
+    // /api/projects/:projectId/sessions/:sessionId endpoint expects.
     (
-      projectName: string,
+      projectId: string,
       sessionId: string,
       sessionTitle: string,
       provider: SessionDeleteConfirmation['provider'] = 'claude',
     ) => {
-      setSessionDeleteConfirmation({ projectName, sessionId, sessionTitle, provider });
+      setSessionDeleteConfirmation({ projectId, sessionId, sessionTitle, provider });
     },
     [],
   );
@@ -413,7 +430,7 @@ export function useSidebarController({
       return;
     }
 
-    const { projectName, sessionId, provider } = sessionDeleteConfirmation;
+    const { projectId, sessionId, provider } = sessionDeleteConfirmation;
     setSessionDeleteConfirmation(null);
 
     try {
@@ -423,7 +440,8 @@ export function useSidebarController({
       } else if (provider === 'gemini') {
         response = await api.deleteGeminiSession(sessionId);
       } else {
-        response = await api.deleteSession(projectName, sessionId);
+        // Claude sessions are owned by the DB project row; pass projectId.
+        response = await api.deleteSession(projectId, sessionId);
       }
 
       if (response.ok) {
@@ -461,13 +479,15 @@ export function useSidebarController({
     const isEmpty = sessionCount === 0;
 
     setDeleteConfirmation(null);
-    setDeletingProjects((prev) => new Set([...prev, project.name]));
+    // Track in-flight deletes by projectId so the UI can disable actions
+    // even if the project object is rebuilt while the request is flying.
+    setDeletingProjects((prev) => new Set([...prev, project.projectId]));
 
     try {
-      const response = await api.deleteProject(project.name, !isEmpty, deleteData);
+      const response = await api.deleteProject(project.projectId, !isEmpty, deleteData);
 
       if (response.ok) {
-        onProjectDelete?.(project.name);
+        onProjectDelete?.(project.projectId);
       } else {
         const error = (await response.json()) as { error?: string };
         alert(error.error || t('messages.deleteProjectFailed'));
@@ -478,7 +498,7 @@ export function useSidebarController({
     } finally {
       setDeletingProjects((prev) => {
         const next = new Set(prev);
-        next.delete(project.name);
+        next.delete(project.projectId);
         return next;
       });
     }
@@ -486,19 +506,21 @@ export function useSidebarController({
 
   const loadMoreSessions = useCallback(
     async (project: Project) => {
-      const hasMoreOverride = projectHasMoreOverrides[project.name];
+      // Per-project bookkeeping (additionalSessions, loadingSessions,
+      // projectHasMoreOverrides) is indexed by the DB `projectId`.
+      const hasMoreOverride = projectHasMoreOverrides[project.projectId];
       const canLoadMore =
         hasMoreOverride !== undefined ? hasMoreOverride : project.sessionMeta?.hasMore === true;
-      if (!canLoadMore || loadingSessions[project.name]) {
+      if (!canLoadMore || loadingSessions[project.projectId]) {
         return;
       }
 
-      setLoadingSessions((prev) => ({ ...prev, [project.name]: true }));
+      setLoadingSessions((prev) => ({ ...prev, [project.projectId]: true }));
 
       try {
         const currentSessionCount =
-          (project.sessions?.length || 0) + (additionalSessions[project.name]?.length || 0);
-        const response = await api.sessions(project.name, 5, currentSessionCount);
+          (project.sessions?.length || 0) + (additionalSessions[project.projectId]?.length || 0);
+        const response = await api.sessions(project.projectId, 5, currentSessionCount);
 
         if (!response.ok) {
           return;
@@ -511,17 +533,17 @@ export function useSidebarController({
 
         setAdditionalSessions((prev) => ({
           ...prev,
-          [project.name]: [...(prev[project.name] || []), ...(result.sessions || [])],
+          [project.projectId]: [...(prev[project.projectId] || []), ...(result.sessions || [])],
         }));
 
         if (result.hasMore === false) {
           // Keep hasMore state in local hook state instead of mutating the project prop object.
-          setProjectHasMoreOverrides((prev) => ({ ...prev, [project.name]: false }));
+          setProjectHasMoreOverrides((prev) => ({ ...prev, [project.projectId]: false }));
         }
       } catch (error) {
         console.error('Error loading more sessions:', error);
       } finally {
-        setLoadingSessions((prev) => ({ ...prev, [project.name]: false }));
+        setLoadingSessions((prev) => ({ ...prev, [project.projectId]: false }));
       }
     },
     [additionalSessions, loadingSessions, projectHasMoreOverrides],
@@ -545,7 +567,9 @@ export function useSidebarController({
   }, [onRefresh]);
 
   const updateSessionSummary = useCallback(
-    async (_projectName: string, sessionId: string, summary: string, provider: LLMProvider) => {
+    // `_projectId` is unused by the rename endpoint but preserved in the
+    // callback signature so existing wiring from sidebar components works.
+    async (_projectId: string, sessionId: string, summary: string, provider: LLMProvider) => {
       const trimmed = summary.trim();
       if (!trimmed) {
         setEditingSession(null);