From 1d7f3f96412bbdcb917fb15b2fa024de6c121f6f Mon Sep 17 00:00:00 2001
From: Igor <igor.levochkin@xrtc.io>
Date: Sat, 9 May 2026 09:22:01 +0700
Subject: [PATCH 1/5] Add sidebar project pinning

---
 .../raw/features/sidebar-project-pinning.md   |  11 ++
 .../wiki/concepts/sidebar-project-pinning.md  |  25 ++++
 llm-wiki/wiki/index.md                        |   2 +
 llm-wiki/wiki/log.md                          |   6 +
 src/App.vue                                   |  14 ++-
 src/api/codexGateway.ts                       |   3 +
 src/components/sidebar/SidebarThreadTree.vue  |  17 +++
 src/composables/useDesktopState.test.ts       |  30 +++++
 src/composables/useDesktopState.ts            | 107 +++++++++++++++++-
 src/server/codexAppServerBridge.ts            |   7 ++
 tests.md                                      |  32 ++++++
 11 files changed, 249 insertions(+), 5 deletions(-)
 create mode 100644 llm-wiki/raw/features/sidebar-project-pinning.md
 create mode 100644 llm-wiki/wiki/concepts/sidebar-project-pinning.md

diff --git a/llm-wiki/raw/features/sidebar-project-pinning.md b/llm-wiki/raw/features/sidebar-project-pinning.md
new file mode 100644
index 000000000..dd0ba1b31
--- /dev/null
+++ b/llm-wiki/raw/features/sidebar-project-pinning.md
@@ -0,0 +1,11 @@
+# Source: Sidebar Project Pinning
+
+Date: 2026-05-09
+
+The sidebar now mirrors Codex.app project pinning. Codex.app exposes `Pin project` from each project row action menu and persists the selection in `~/.codex/.codex-global-state.json` under `pinned-project-ids`.
+
+The web bridge reads and writes this key through `/codex-api/workspace-roots-state` as `pinnedProjectIds`. Existing workspace root fields remain preserved when pinning changes: `electron-saved-workspace-roots`, `electron-workspace-root-labels`, `active-workspace-roots`, `project-order`, and `remote-projects`.
+
+Pinned projects are rendered before regular projects while preserving the pinned order. Non-pinned projects continue to follow Codex `project-order`. Duplicate leaf-name projects are resolved through the same full-path disambiguation used for workspace roots, and remote projects keep their remote project id as the pinned id.
+
+The project action menu now shows `Pin project` or `Unpin project` depending on the current pinned state. Pinning does not rewrite manual project order; it only updates `pinned-project-ids`.
diff --git a/llm-wiki/wiki/concepts/sidebar-project-pinning.md b/llm-wiki/wiki/concepts/sidebar-project-pinning.md
new file mode 100644
index 000000000..8bc249c40
--- /dev/null
+++ b/llm-wiki/wiki/concepts/sidebar-project-pinning.md
@@ -0,0 +1,25 @@
+# Sidebar Project Pinning
+
+Sidebar project pinning follows Codex.app global state instead of treating pinning as a local-only reorder.
+
+## Behavior
+
+- Project row actions include `Pin project` for unpinned projects and `Unpin project` for pinned projects.
+- Pinned projects render before regular projects.
+- Pinned project order follows `pinned-project-ids`.
+- Regular project order continues to follow `project-order`.
+- Pinning preserves the existing workspace-root state fields and only changes `pinned-project-ids`.
+
+## State
+
+Codex.app stores pinned project ids in `~/.codex/.codex-global-state.json` under `pinned-project-ids`. The web bridge exposes that key as `pinnedProjectIds` in `/codex-api/workspace-roots-state`.
+
+Local projects use the workspace root path as the durable pinned id. Remote projects use the remote project id. Duplicate folder names keep using the existing full-path project disambiguation before matching pinned rows.
+
+## Verification Notes
+
+Manual verification should check both light and dark themes because this feature changes the project row action menu. A focused unit test should assert that a pinned project appears before the rest of the Codex `project-order`.
+
+## Sources
+
+- [Sidebar project pinning source](../../raw/features/sidebar-project-pinning.md)
diff --git a/llm-wiki/wiki/index.md b/llm-wiki/wiki/index.md
index 94b762bd3..142e545ca 100644
--- a/llm-wiki/wiki/index.md
+++ b/llm-wiki/wiki/index.md
@@ -12,6 +12,7 @@
 - [concepts/merge-to-main-workflow.md](./concepts/merge-to-main-workflow.md): branch integration and conflict-resolution workflow.
 - [concepts/opencode-zen-big-pickle.md](./concepts/opencode-zen-big-pickle.md): OpenCode Zen Big Pickle model configuration for Codex CLI and OpenCode CLI.
 - [concepts/realtime-chat-rendering.md](./concepts/realtime-chat-rendering.md): realtime chat rendering, sync-churn reduction, and inline media sanitization.
+- [concepts/sidebar-project-pinning.md](./concepts/sidebar-project-pinning.md): Codex.app-style project pinning state, ordering, and sidebar menu behavior.
 - [concepts/skills-route-ui.md](./concepts/skills-route-ui.md): Skills route naming, first-launch Plugins card persistence, dark-theme fixes, and verification lessons.
 - [concepts/thread-heartbeat-automations.md](./concepts/thread-heartbeat-automations.md): thread-scoped heartbeat automation storage, multi-automation management, and manual run behavior.
 
@@ -19,6 +20,7 @@
 - [../raw/features/integrated-terminal.md](../raw/features/integrated-terminal.md): source facts for the integrated terminal implementation and follow-up tests.
 - [../raw/features/directory-hub-composio-skills-search.md](../raw/features/directory-hub-composio-skills-search.md): source facts for Directory Hub, Composio connectors, Skills search/install, and edge-case tests.
 - [../raw/features/realtime-chat-rendering-inline-media.md](../raw/features/realtime-chat-rendering-inline-media.md): source facts for realtime chat rendering and inline media sanitization.
+- [../raw/features/sidebar-project-pinning.md](../raw/features/sidebar-project-pinning.md): source facts for Codex.app-style sidebar project pinning.
 - [../raw/features/skills-route-ui-and-first-launch-card.md](../raw/features/skills-route-ui-and-first-launch-card.md): source facts for the Skills route rename, first-launch Plugins card, dark-theme fix, and dev-server workflow adjustment.
 - [../raw/features/thread-heartbeat-automations.md](../raw/features/thread-heartbeat-automations.md): source facts for thread heartbeat automations, multiple automations per thread, and Run now queue behavior.
 - [../raw/projects/codex-web-local.md](../raw/projects/codex-web-local.md): immutable source snapshot for project facts.
diff --git a/llm-wiki/wiki/log.md b/llm-wiki/wiki/log.md
index 6f1bc3d43..687ed2cbb 100644
--- a/llm-wiki/wiki/log.md
+++ b/llm-wiki/wiki/log.md
@@ -46,3 +46,9 @@
 - Updated wiki page: `concepts/opencode-zen-big-pickle.md`.
 - Documents: DeepSeek thinking-mode `reasoning_content` round-trip requirement, Chat-shaped Zen proxy endpoint selection, streaming reasoning preservation, Docker validation, and the `/tmp/app.tar` restart gotcha.
 - Updated `index.md`.
+
+## [2026-05-09] ingest | sidebar project pinning
+- Added source: `raw/features/sidebar-project-pinning.md`.
+- Created wiki page: `concepts/sidebar-project-pinning.md`.
+- Documents: Codex.app `pinned-project-ids` state, project menu pin/unpin behavior, pinned ordering before `project-order`, and workspace-root preservation.
+- Updated `index.md`.
diff --git a/src/App.vue b/src/App.vue
index 8106e4068..fbf9c3d42 100644
--- a/src/App.vue
+++ b/src/App.vue
@@ -62,6 +62,7 @@
 
           <SidebarThreadTree :groups="projectGroups" :project-display-name-by-id="projectDisplayNameById"
             :project-git-repo-by-name="projectGitRepoByName"
+            :pinned-project-names="pinnedProjectNames"
             v-if="!isSidebarCollapsed"
             :selected-thread-id="selectedThreadId" :is-loading="isLoadingThreads"
             :search-query="sidebarSearchQuery"
@@ -71,6 +72,7 @@
             @browse-thread-files="onBrowseThreadFiles"
             @browse-project-files="onBrowseProjectFiles"
             @request-project-git-status="onRequestProjectGitStatus"
+            @set-project-pinned="onSetProjectPinned"
             @create-project-worktree="onCreateProjectWorktree"
             @rename-thread="onRenameThread"
             @fork-thread="onForkThread"
@@ -1179,6 +1181,7 @@ const WHISPER_LANGUAGES: Record<string, string> = {
 
 const {
   projectGroups,
+  pinnedProjectNames,
   projectDisplayNameById,
   selectedThread,
   selectedThreadTokenUsage,
@@ -1230,6 +1233,7 @@ const {
   removeProject,
   reorderProject,
   pinProjectToTop,
+  setProjectPinned,
   startPolling,
   stopPolling,
   primeSelectedThread,
@@ -1263,10 +1267,11 @@ const gitRepoStatusRequestByCwd = new Map<string, Promise<boolean>>()
 const newWorktreeBaseBranch = ref('')
 const worktreeBranchOptions = ref<WorktreeBranchOption[]>([])
 const isLoadingWorktreeBranches = ref(false)
-const workspaceRootOptionsState = ref<{ order: string[]; labels: Record<string, string>; projectOrder: string[] }>({
+const workspaceRootOptionsState = ref<{ order: string[]; labels: Record<string, string>; projectOrder: string[]; pinnedProjectIds: string[] }>({
   order: [],
   labels: {},
   projectOrder: [],
+  pinnedProjectIds: [],
 })
 const worktreeInitStatus = ref<{ phase: 'idle' | 'running' | 'error'; title: string; message: string }>({
   phase: 'idle',
@@ -2438,6 +2443,10 @@ function onReorderProject(payload: { projectName: string; toIndex: number }): vo
   reorderProject(payload.projectName, payload.toIndex)
 }
 
+function onSetProjectPinned(payload: { projectName: string; pinned: boolean }): void {
+  void setProjectPinned(payload.projectName, payload.pinned)
+}
+
 function onRequestProjectGitStatus(projectName: string): void {
   const group = projectGroups.value.find((entry) => entry.projectName === projectName)
   const cwd = resolvePreferredLocalCwd(projectName, group?.threads[0]?.cwd?.trim() ?? '')
@@ -3283,9 +3292,10 @@ async function loadWorkspaceRootOptionsState(): Promise<void> {
       order: [...state.order],
       labels: { ...state.labels },
       projectOrder: [...state.projectOrder],
+      pinnedProjectIds: [...(state.pinnedProjectIds ?? [])],
     }
   } catch {
-    workspaceRootOptionsState.value = { order: [], labels: {}, projectOrder: [] }
+    workspaceRootOptionsState.value = { order: [], labels: {}, projectOrder: [], pinnedProjectIds: [] }
   }
 }
 
diff --git a/src/api/codexGateway.ts b/src/api/codexGateway.ts
index 6f64305a7..e4dfea5ab 100644
--- a/src/api/codexGateway.ts
+++ b/src/api/codexGateway.ts
@@ -268,6 +268,7 @@ export type WorkspaceRootsState = {
   labels: Record<string, string>
   active: string[]
   projectOrder: string[]
+  pinnedProjectIds?: string[]
   remoteProjects?: Array<{
     id: string
     hostId: string
@@ -2242,6 +2243,7 @@ function normalizeWorkspaceRootsState(payload: unknown): WorkspaceRootsState {
     labels,
     active: normalizeArray(record.active).map((value) => normalizePathForUi(value)),
     projectOrder: normalizeArray(record.projectOrder).map((value) => normalizePathForUi(value)),
+    pinnedProjectIds: normalizeArray(record.pinnedProjectIds).map((value) => normalizePathForUi(value)),
     remoteProjects: Array.isArray(record.remoteProjects)
       ? record.remoteProjects.flatMap((item) => {
         if (!item || typeof item !== 'object' || Array.isArray(item)) return []
@@ -2351,6 +2353,7 @@ function cloneWorkspaceRootsState(state: WorkspaceRootsState): WorkspaceRootsSta
     labels: { ...state.labels },
     active: [...state.active],
     projectOrder: [...state.projectOrder],
+    pinnedProjectIds: [...(state.pinnedProjectIds ?? [])],
     remoteProjects: state.remoteProjects?.map((item) => ({ ...item })) ?? [],
   }
 }
diff --git a/src/components/sidebar/SidebarThreadTree.vue b/src/components/sidebar/SidebarThreadTree.vue
index 9c92ca139..dc510b496 100644
--- a/src/components/sidebar/SidebarThreadTree.vue
+++ b/src/components/sidebar/SidebarThreadTree.vue
@@ -316,6 +316,9 @@
                       <button class="project-menu-item" type="button" @click="onBrowseProjectFiles(group.projectName)">
                         Browse files
                       </button>
+                      <button class="project-menu-item" type="button" @click="onToggleProjectPinned(group.projectName)">
+                        {{ isProjectPinned(group.projectName) ? 'Unpin project' : 'Pin project' }}
+                      </button>
                       <button
                         v-if="projectGitRepoByName[group.projectName]"
                         class="project-menu-item"
@@ -828,6 +831,7 @@ const props = defineProps<{
   groups: UiProjectGroup[]
   projectDisplayNameById: Record<string, string>
   projectGitRepoByName: Record<string, boolean>
+  pinnedProjectNames: string[]
   selectedThreadId: string
   isLoading: boolean
   searchQuery: string
@@ -843,6 +847,7 @@ const emit = defineEmits<{
   'browse-thread-files': [threadId: string]
   'browse-project-files': [projectName: string]
   'request-project-git-status': [projectName: string]
+  'set-project-pinned': [payload: { projectName: string; pinned: boolean }]
   'create-project-worktree': [projectName: string]
   'rename-project': [payload: { projectName: string; displayName: string }]
   'rename-thread': [payload: { threadId: string; title: string }]
@@ -1821,6 +1826,10 @@ function isProjectMenuOpen(projectName: string): boolean {
   return openProjectMenuId.value === projectName
 }
 
+function isProjectPinned(projectName: string): boolean {
+  return props.pinnedProjectNames.includes(projectName)
+}
+
 function closeProjectMenu(): void {
   openProjectMenuId.value = ''
   projectMenuMode.value = 'actions'
@@ -1899,6 +1908,14 @@ function onBrowseProjectFiles(projectName: string): void {
   closeProjectMenu()
 }
 
+function onToggleProjectPinned(projectName: string): void {
+  emit('set-project-pinned', {
+    projectName,
+    pinned: !isProjectPinned(projectName),
+  })
+  closeProjectMenu()
+}
+
 function onCreateProjectWorktree(projectName: string): void {
   emit('create-project-worktree', projectName)
   closeProjectMenu()
diff --git a/src/composables/useDesktopState.test.ts b/src/composables/useDesktopState.test.ts
index df04591db..f0a0a425b 100644
--- a/src/composables/useDesktopState.test.ts
+++ b/src/composables/useDesktopState.test.ts
@@ -166,6 +166,36 @@ describe('filterGroupsByWorkspaceRoots', () => {
     ])
   })
 
+  it('places Codex pinned projects before regular project order', () => {
+    const groups: UiProjectGroup[] = [
+      {
+        projectName: 'alpha',
+        threads: [thread('alpha-chat', '/tmp/alpha')],
+      },
+      {
+        projectName: 'beta',
+        threads: [thread('beta-chat', '/tmp/beta')],
+      },
+      {
+        projectName: 'gamma',
+        threads: [thread('gamma-chat', '/tmp/gamma')],
+      },
+    ]
+    const rootsState: WorkspaceRootsState = {
+      order: ['/tmp/alpha', '/tmp/beta', '/tmp/gamma'],
+      labels: {},
+      active: ['/tmp/alpha'],
+      projectOrder: ['/tmp/beta', '/tmp/alpha', '/tmp/gamma'],
+      pinnedProjectIds: ['/tmp/gamma'],
+    }
+
+    expect(filterGroupsByWorkspaceRoots(groups, rootsState).map((group) => group.projectName)).toEqual([
+      'gamma',
+      'beta',
+      'alpha',
+    ])
+  })
+
   it('keeps empty duplicate workspace roots visible in Codex project order', () => {
     const groups: UiProjectGroup[] = [
       {
diff --git a/src/composables/useDesktopState.ts b/src/composables/useDesktopState.ts
index 17c83a867..6c64f690f 100644
--- a/src/composables/useDesktopState.ts
+++ b/src/composables/useDesktopState.ts
@@ -1070,6 +1070,38 @@ function getWorkspaceProjectOrderNames(
   })
 }
 
+function getWorkspacePinnedProjectNames(
+  rootsState: WorkspaceRootsState | null,
+  duplicateLeafNames: Set<string>,
+): string[] {
+  if (!rootsState) return []
+  const remoteProjectsById = getRemoteProjectById(rootsState)
+  return (rootsState.pinnedProjectIds ?? []).map((projectId) => {
+    if (remoteProjectsById.has(projectId)) return projectId
+    const normalizedRootPath = normalizePathForUi(projectId).trim()
+    const leafName = toProjectNameFromWorkspaceRoot(normalizedRootPath)
+    return duplicateLeafNames.has(leafName) ? normalizedRootPath : leafName
+  }).filter((name) => name.length > 0)
+}
+
+function orderGroupsWithPinnedProjects(
+  groups: UiProjectGroup[],
+  pinnedProjectNames: string[],
+): UiProjectGroup[] {
+  if (pinnedProjectNames.length === 0) return groups
+  const pinnedIndexByName = new Map(pinnedProjectNames.map((name, index) => [name, index]))
+  return [...groups].sort((first, second) => {
+    const firstPinnedIndex = pinnedIndexByName.get(first.projectName)
+    const secondPinnedIndex = pinnedIndexByName.get(second.projectName)
+    if (firstPinnedIndex !== undefined && secondPinnedIndex !== undefined) {
+      return firstPinnedIndex - secondPinnedIndex
+    }
+    if (firstPinnedIndex !== undefined) return -1
+    if (secondPinnedIndex !== undefined) return 1
+    return 0
+  })
+}
+
 function matchesWorkspaceRootProject(rootPath: string, projectName: string): boolean {
   const normalizedRootPath = normalizePathForUi(rootPath).trim()
   return normalizedRootPath === projectName || toProjectNameFromWorkspaceRoot(rootPath) === projectName
@@ -1163,15 +1195,17 @@ function orderGroupsByWorkspaceProjectOrder(
   duplicateLeafNames: Set<string>,
 ): UiProjectGroup[] {
   const order = getWorkspaceProjectOrderNames(rootsState, duplicateLeafNames)
-  if (order.length === 0) return groups
+  const pinnedProjectNames = getWorkspacePinnedProjectNames(rootsState, duplicateLeafNames)
+  if (order.length === 0) return orderGroupsWithPinnedProjects(groups, pinnedProjectNames)
   const orderIndexByName = new Map(order.map((name, index) => [name, index]))
-  return [...groups].sort((first, second) => {
+  const orderedGroups = [...groups].sort((first, second) => {
     if (isProjectlessGroup(first) || isProjectlessGroup(second)) return 0
     const firstIndex = orderIndexByName.get(first.projectName) ?? Number.POSITIVE_INFINITY
     const secondIndex = orderIndexByName.get(second.projectName) ?? Number.POSITIVE_INFINITY
     if (firstIndex === secondIndex) return 0
     return firstIndex - secondIndex
   })
+  return orderGroupsWithPinnedProjects(orderedGroups, pinnedProjectNames)
 }
 
 function collectDuplicateProjectLeafNames(groups: UiProjectGroup[], rootsState: WorkspaceRootsState | null): Set<string> {
@@ -1390,6 +1424,7 @@ export function useDesktopState() {
   const readStateByThreadId = ref<Record<string, string>>(loadReadStateMap())
   const unreadCutoffIso = ref(loadUnreadCutoffIso())
   const projectOrder = ref<string[]>(loadProjectOrder())
+  const pinnedProjectNames = ref<string[]>([])
   const projectDisplayNameById = ref<Record<string, string>>(loadProjectDisplayNames())
   const loadedVersionByThreadId = ref<Record<string, string>>({})
   const loadedMessagesByThreadId = ref<Record<string, boolean>>({})
@@ -3943,6 +3978,8 @@ export function useDesktopState() {
 
   function applyThreadGroups(groups: UiProjectGroup[], rootsState: WorkspaceRootsState | null): void {
     const visibleGroups = filterGroupsByWorkspaceRoots(groups, rootsState)
+    const duplicateLeafNames = collectDuplicateProjectLeafNames(groups, rootsState)
+    pinnedProjectNames.value = getWorkspacePinnedProjectNames(rootsState, duplicateLeafNames)
     const hasWorkspaceRootsState = Boolean(
       rootsState && (rootsState.order.length > 0 || rootsState.projectOrder.length > 0 || (rootsState.remoteProjects ?? []).length > 0),
     )
@@ -3960,7 +3997,10 @@ export function useDesktopState() {
       }
     }
 
-    const orderedGroups = orderGroupsByProjectOrder(visibleGroups, projectOrder.value)
+    const orderedGroups = orderGroupsWithPinnedProjects(
+      orderGroupsByProjectOrder(visibleGroups, projectOrder.value),
+      pinnedProjectNames.value,
+    )
     markServerListedThreads(new Set(flattenThreads(orderedGroups).map((thread) => thread.id)))
     const mergedWithInProgress = mergeIncomingWithLocalInProgressThreads(
       sourceGroups.value,
@@ -4962,6 +5002,7 @@ export function useDesktopState() {
           labels: nextLabels,
           active: rootsState.active,
           projectOrder: rootsState.projectOrder,
+          pinnedProjectIds: rootsState.pinnedProjectIds ?? [],
         })
       }
     } catch {
@@ -5039,6 +5080,7 @@ export function useDesktopState() {
           labels: omitKeys(rootsState.labels, removedRootPaths),
           active: fallbackActive,
           projectOrder: rootsState.projectOrder.filter((item) => item !== projectName && !removedRootPaths.has(item)),
+          pinnedProjectIds: (rootsState.pinnedProjectIds ?? []).filter((item) => item !== projectName && !removedRootPaths.has(item)),
         })
         return
       } catch {
@@ -5085,6 +5127,61 @@ export function useDesktopState() {
     void persistProjectOrderToWorkspaceRoots()
   }
 
+  function resolveProjectPinnedId(rootsState: WorkspaceRootsState, projectName: string): string {
+    const normalizedName = normalizePathForUi(projectName).trim()
+    if (!normalizedName) return ''
+    if ((rootsState.remoteProjects ?? []).some((project) => project.id === normalizedName)) return normalizedName
+    for (const rootPath of rootsState.order) {
+      if (matchesWorkspaceRootProject(rootPath, normalizedName)) return rootPath
+    }
+    const group = sourceGroups.value.find((item) => item.projectName === normalizedName)
+    const cwd = group?.threads[0]?.cwd?.trim() ?? ''
+    return cwd || normalizedName
+  }
+
+  function applyPinnedProjectNamesFromRootsState(rootsState: WorkspaceRootsState | null, groups: UiProjectGroup[] = sourceGroups.value): void {
+    const duplicateLeafNames = collectDuplicateProjectLeafNames(groups, rootsState)
+    pinnedProjectNames.value = getWorkspacePinnedProjectNames(rootsState, duplicateLeafNames)
+  }
+
+  function isProjectPinned(projectName: string): boolean {
+    return pinnedProjectNames.value.includes(projectName)
+  }
+
+  async function setProjectPinned(projectName: string, pinned: boolean): Promise<void> {
+    const normalizedName = normalizePathForUi(projectName).trim()
+    if (!normalizedName) return
+
+    try {
+      const rootsState = await getWorkspaceRootsState()
+      const pinnedProjectId = resolveProjectPinnedId(rootsState, normalizedName)
+      if (!pinnedProjectId) return
+      const currentPinnedProjectIds = rootsState.pinnedProjectIds ?? []
+      const nextPinnedProjectIds = pinned
+        ? [pinnedProjectId, ...currentPinnedProjectIds.filter((item) => item !== pinnedProjectId)]
+        : currentPinnedProjectIds.filter((item) => item !== pinnedProjectId)
+
+      if (areStringArraysEqual(currentPinnedProjectIds, nextPinnedProjectIds)) return
+
+      await setWorkspaceRootsState({
+        order: rootsState.order,
+        labels: rootsState.labels,
+        active: rootsState.active,
+        projectOrder: rootsState.projectOrder,
+        pinnedProjectIds: nextPinnedProjectIds,
+      })
+
+      const nextRootsState: WorkspaceRootsState = {
+        ...rootsState,
+        pinnedProjectIds: nextPinnedProjectIds,
+      }
+      applyPinnedProjectNamesFromRootsState(nextRootsState)
+      applyThreadGroups(sourceGroups.value, nextRootsState)
+    } catch (unknownError) {
+      error.value = unknownError instanceof Error ? unknownError.message : 'Failed to update pinned project'
+    }
+  }
+
   async function persistProjectOrderToWorkspaceRoots(): Promise<void> {
     try {
       const rootsState = await getWorkspaceRootsState()
@@ -5095,6 +5192,7 @@ export function useDesktopState() {
         labels: rootsState.labels,
         active: nextState.active,
         projectOrder: nextState.projectOrder,
+        pinnedProjectIds: rootsState.pinnedProjectIds ?? [],
       })
     } catch {
       // Keep local project order when global state persistence is unavailable.
@@ -5345,6 +5443,7 @@ export function useDesktopState() {
 
   return {
     projectGroups,
+    pinnedProjectNames,
     projectDisplayNameById,
     selectedThread,
     selectedThreadTokenUsage,
@@ -5403,6 +5502,8 @@ export function useDesktopState() {
     removeProject,
     reorderProject,
     pinProjectToTop,
+    isProjectPinned,
+    setProjectPinned,
     startPolling,
     stopPolling,
     primeSelectedThread,
diff --git a/src/server/codexAppServerBridge.ts b/src/server/codexAppServerBridge.ts
index 93c0bf849..2a80e729d 100644
--- a/src/server/codexAppServerBridge.ts
+++ b/src/server/codexAppServerBridge.ts
@@ -81,6 +81,7 @@ type WorkspaceRootsState = {
   labels: Record<string, string>
   active: string[]
   projectOrder: string[]
+  pinnedProjectIds: string[]
   remoteProjects: Array<{
     id: string
     hostId: string
@@ -3886,6 +3887,7 @@ async function readWorkspaceRootsState(): Promise<WorkspaceRootsState> {
     labels: normalizeStringRecord(payload['electron-workspace-root-labels']),
     active: normalizeStringArray(payload['active-workspace-roots']),
     projectOrder: normalizeStringArray(payload['project-order']),
+    pinnedProjectIds: normalizeStringArray(payload['pinned-project-ids']),
     remoteProjects: normalizeRemoteProjects(payload['remote-projects']),
   }
 }
@@ -3904,6 +3906,7 @@ async function writeWorkspaceRootsState(nextState: WorkspaceRootsState): Promise
   payload['electron-workspace-root-labels'] = normalizeStringRecord(nextState.labels)
   payload['active-workspace-roots'] = normalizeStringArray(nextState.active)
   payload['project-order'] = normalizeStringArray(nextState.projectOrder)
+  payload['pinned-project-ids'] = normalizeStringArray(nextState.pinnedProjectIds)
 
   await writeFile(statePath, JSON.stringify(payload), 'utf8')
 }
@@ -3947,6 +3950,7 @@ async function persistWorkspaceRoot(workspaceRoot: string, label = ''): Promise<
       labels: nextLabels,
       active: prependUniqueString(normalizedRoot, existingState.active),
       projectOrder: prependUniqueString(normalizedRoot, existingState.projectOrder),
+      pinnedProjectIds: existingState.pinnedProjectIds,
       remoteProjects: existingState.remoteProjects,
     }
   })
@@ -6657,6 +6661,9 @@ export function createCodexBridgeMiddleware(): CodexBridgeMiddleware {
           projectOrder: Array.isArray(record.projectOrder)
             ? normalizeStringArray(record.projectOrder)
             : existingState.projectOrder,
+          pinnedProjectIds: Array.isArray(record.pinnedProjectIds)
+            ? normalizeStringArray(record.pinnedProjectIds)
+            : existingState.pinnedProjectIds,
           remoteProjects: existingState.remoteProjects,
         }))
         setJson(res, 200, { ok: true })
diff --git a/tests.md b/tests.md
index 365c301f1..2f1de345e 100644
--- a/tests.md
+++ b/tests.md
@@ -271,6 +271,38 @@ This file tracks manual regression and feature verification steps.
 
 ---
 
+### Sidebar project pinning
+
+#### Feature/Change Name
+Project rows can be pinned and unpinned from the sidebar action menu using Codex.app-compatible `pinned-project-ids` state.
+
+#### Prerequisites/Setup
+1. Dev server running (`pnpm run dev`)
+2. Sidebar contains at least three visible projects
+3. Light theme and dark theme both available from the appearance switcher
+
+#### Steps
+1. In light theme, open the sidebar Projects section.
+2. Open a non-top project action menu and click `Pin project`.
+3. Confirm the project moves above the regular projects and its action menu now shows `Unpin project`.
+4. Refresh the browser tab and confirm the pinned project remains above regular projects.
+5. Inspect `~/.codex/.codex-global-state.json` and confirm `pinned-project-ids` contains the pinned project root or remote project id.
+6. Open the pinned project action menu and click `Unpin project`.
+7. Confirm the project returns to its normal `project-order` position and `pinned-project-ids` no longer contains that project.
+8. Switch to dark theme and repeat steps 2-7 with a different project.
+
+#### Expected Results
+- Project action menus expose `Pin project` for unpinned projects and `Unpin project` for pinned projects.
+- Pinned projects render before non-pinned projects without rewriting the saved `project-order`.
+- Pin and unpin persist through `/codex-api/workspace-roots-state` and Codex global state.
+- Duplicate folder-name projects and remote project rows pin the intended project id.
+- Project menu items and row controls remain readable in light and dark themes.
+
+#### Rollback/Cleanup
+- Unpin any projects pinned during verification.
+
+---
+
 ### Startup avoids duplicate setup probes
 
 #### Feature/Change Name

From e4f191da850b9c4f337da7bf2600de00237395bf Mon Sep 17 00:00:00 2001
From: Igor <igor.levochkin@xrtc.io>
Date: Sat, 9 May 2026 11:17:26 +0700
Subject: [PATCH 2/5] Fix project pinning review findings

---
 src/api/codexGateway.ts                 |  6 +-
 src/composables/useDesktopState.test.ts | 75 +++++++++++++++++++++++++
 src/composables/useDesktopState.ts      |  6 +-
 3 files changed, 83 insertions(+), 4 deletions(-)

diff --git a/src/api/codexGateway.ts b/src/api/codexGateway.ts
index e4dfea5ab..0cb3f0625 100644
--- a/src/api/codexGateway.ts
+++ b/src/api/codexGateway.ts
@@ -2731,6 +2731,7 @@ async function readJsonResponse(response: Response): Promise<unknown> {
 }
 
 export async function setWorkspaceRootsState(nextState: WorkspaceRootsState): Promise<void> {
+  const previousState = cachedWorkspaceRootsState
   const response = await fetch('/codex-api/workspace-roots-state', {
     method: 'PUT',
     headers: { 'Content-Type': 'application/json' },
@@ -2739,7 +2740,10 @@ export async function setWorkspaceRootsState(nextState: WorkspaceRootsState): Pr
   if (!response.ok) {
     throw new Error('Failed to save workspace roots state')
   }
-  cachedWorkspaceRootsState = cloneWorkspaceRootsState(nextState)
+  cachedWorkspaceRootsState = cloneWorkspaceRootsState({
+    ...nextState,
+    remoteProjects: nextState.remoteProjects ?? previousState?.remoteProjects ?? [],
+  })
 }
 
 export async function openProjectRoot(path: string, options?: { createIfMissing?: boolean; label?: string }): Promise<string> {
diff --git a/src/composables/useDesktopState.test.ts b/src/composables/useDesktopState.test.ts
index f0a0a425b..aec94d0c2 100644
--- a/src/composables/useDesktopState.test.ts
+++ b/src/composables/useDesktopState.test.ts
@@ -196,6 +196,36 @@ describe('filterGroupsByWorkspaceRoots', () => {
     ])
   })
 
+  it('keeps projectless groups stable when projects are pinned', () => {
+    const groups: UiProjectGroup[] = [
+      {
+        projectName: 'Projectless',
+        threads: [thread('projectless-chat', '')],
+      },
+      {
+        projectName: 'alpha',
+        threads: [thread('alpha-chat', '/tmp/alpha')],
+      },
+      {
+        projectName: 'beta',
+        threads: [thread('beta-chat', '/tmp/beta')],
+      },
+    ]
+    const rootsState: WorkspaceRootsState = {
+      order: ['/tmp/alpha', '/tmp/beta'],
+      labels: {},
+      active: ['/tmp/alpha'],
+      projectOrder: ['/tmp/alpha', '/tmp/beta'],
+      pinnedProjectIds: ['/tmp/beta'],
+    }
+
+    expect(filterGroupsByWorkspaceRoots(groups, rootsState).map((group) => group.projectName)).toEqual([
+      'Projectless',
+      'beta',
+      'alpha',
+    ])
+  })
+
   it('keeps empty duplicate workspace roots visible in Codex project order', () => {
     const groups: UiProjectGroup[] = [
       {
@@ -311,6 +341,51 @@ describe('filterGroupsByWorkspaceRoots', () => {
   })
 })
 
+describe('project pinning state', () => {
+  it('preserves remote projects when persisting a project pin', async () => {
+    installTestWindow()
+    const remoteProjects = [{
+      id: 'remote-project-id',
+      hostId: 'remote-ssh-discovered:a1',
+      remotePath: '/home/ubuntu',
+      label: 'ubuntu',
+    }]
+    gatewayMocks.getWorkspaceRootsState.mockResolvedValue({
+      order: ['/tmp/alpha'],
+      labels: {},
+      active: ['/tmp/alpha'],
+      projectOrder: ['/tmp/alpha'],
+      pinnedProjectIds: [],
+      remoteProjects,
+    })
+
+    const state = useDesktopState()
+    await state.setProjectPinned('alpha', true)
+
+    expect(gatewayMocks.setWorkspaceRootsState).toHaveBeenCalledWith(expect.objectContaining({
+      pinnedProjectIds: ['/tmp/alpha'],
+      remoteProjects,
+    }))
+  })
+
+  it('does not persist non-durable project pin ids', async () => {
+    installTestWindow()
+    gatewayMocks.getWorkspaceRootsState.mockResolvedValue({
+      order: ['/tmp/alpha'],
+      labels: {},
+      active: ['/tmp/alpha'],
+      projectOrder: ['/tmp/alpha'],
+      pinnedProjectIds: [],
+      remoteProjects: [],
+    })
+
+    const state = useDesktopState()
+    await state.setProjectPinned('Projectless', true)
+
+    expect(gatewayMocks.setWorkspaceRootsState).not.toHaveBeenCalled()
+  })
+})
+
 describe('removeThreadFromGroups', () => {
   it('removes an archived thread and drops the now-empty project group', () => {
     const groups: UiProjectGroup[] = [
diff --git a/src/composables/useDesktopState.ts b/src/composables/useDesktopState.ts
index 6c64f690f..a5e192d3f 100644
--- a/src/composables/useDesktopState.ts
+++ b/src/composables/useDesktopState.ts
@@ -1091,6 +1091,7 @@ function orderGroupsWithPinnedProjects(
   if (pinnedProjectNames.length === 0) return groups
   const pinnedIndexByName = new Map(pinnedProjectNames.map((name, index) => [name, index]))
   return [...groups].sort((first, second) => {
+    if (isProjectlessGroup(first) || isProjectlessGroup(second)) return 0
     const firstPinnedIndex = pinnedIndexByName.get(first.projectName)
     const secondPinnedIndex = pinnedIndexByName.get(second.projectName)
     if (firstPinnedIndex !== undefined && secondPinnedIndex !== undefined) {
@@ -5134,9 +5135,7 @@ export function useDesktopState() {
     for (const rootPath of rootsState.order) {
       if (matchesWorkspaceRootProject(rootPath, normalizedName)) return rootPath
     }
-    const group = sourceGroups.value.find((item) => item.projectName === normalizedName)
-    const cwd = group?.threads[0]?.cwd?.trim() ?? ''
-    return cwd || normalizedName
+    return ''
   }
 
   function applyPinnedProjectNamesFromRootsState(rootsState: WorkspaceRootsState | null, groups: UiProjectGroup[] = sourceGroups.value): void {
@@ -5169,6 +5168,7 @@ export function useDesktopState() {
         active: rootsState.active,
         projectOrder: rootsState.projectOrder,
         pinnedProjectIds: nextPinnedProjectIds,
+        remoteProjects: rootsState.remoteProjects ?? [],
       })
 
       const nextRootsState: WorkspaceRootsState = {

From 6aea550e29e18127feb8eb858e2aad9d1820c815 Mon Sep 17 00:00:00 2001
From: Igor <igor.levochkin@xrtc.io>
Date: Sat, 9 May 2026 11:18:48 +0700
Subject: [PATCH 3/5] Document required Qodo PR workflow

---
 AGENTS.md | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 57c2cd407..4d62a70c0 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -62,9 +62,20 @@
 - Reproduce the issue with a focused test when feasible; if direct reproduction is impractical, document the exact reasoning and code evidence used to accept or reject the finding.
 - Prefer adding or updating a regression test for every accepted review-bot bug before or alongside the fix.
 - Do not patch purely to satisfy a bot comment if the behavior is correct, stale, already fixed, or the proposed change would make the implementation worse.
-- After pushing any commit to an open PR, wait and poll for Qodo/review-bot comments and PR review status for about 30 seconds before reporting the push workflow as complete.
-- After fixing an accepted review-bot finding, run the narrow regression test plus the relevant build/typecheck command, push the commit, and re-check the PR comments/status.
-- In the completion report, distinguish confirmed fixes from stale or rejected bot comments.
+- After creating any PR, always wait for Qodo to finish before reporting the PR workflow as complete:
+  1. Poll the PR with `gh pr view <pr-number> --json comments,reviews,reviewDecision,mergeStateStatus,statusCheckRollup`.
+  2. If the Qodo code-review comment says `Check back in a few minutes`, `is analyzing this pull request`, or otherwise looks like a placeholder, sleep 30 seconds and poll again.
+  3. Continue polling until Qodo posts a completed code-review comment with active counts such as `Bugs (N)`, `Rule violations (N)`, or `Requirement gaps (N)`.
+  4. Do not treat the separate Qodo summary/walkthrough comment as the completed code review.
+- When Qodo reports findings:
+  1. Inspect each finding and classify it as accepted, stale/already fixed, rejected/incorrect, or needs follow-up.
+  2. For each accepted bug, inspect the code path and add or update a focused regression test where feasible.
+  3. Implement the fix, then run the narrow regression test plus the relevant build/typecheck command.
+  4. Commit the fix as its own discrete commit and push it to the PR branch.
+  5. Poll Qodo again using the same 30-second loop until the updated review is complete.
+  6. Repeat until Qodo reports `Bugs (0)`, `Rule violations (0)`, and `Requirement gaps (0)`, or until all remaining findings are explicitly documented as stale/rejected with code evidence.
+- After pushing any commit to an open PR, run the same Qodo wait-and-fix loop before reporting the push workflow as complete.
+- In the completion report, include the PR URL, latest commit, commands run, Qodo final counts, and which bot findings were fixed versus stale/rejected.
 
 ## Performance Audit Rule (MANDATORY)
 

From 03e036e56d529dcc8720aa674803934c48501f1c Mon Sep 17 00:00:00 2001
From: Igor <igor.levochkin@xrtc.io>
Date: Sat, 9 May 2026 11:26:36 +0700
Subject: [PATCH 4/5] Fix pinned project visible-name ordering

---
 src/composables/useDesktopState.test.ts | 25 +++++++++++++++++++
 src/composables/useDesktopState.ts      | 33 ++++++++++++++++---------
 2 files changed, 47 insertions(+), 11 deletions(-)

diff --git a/src/composables/useDesktopState.test.ts b/src/composables/useDesktopState.test.ts
index aec94d0c2..8a3a086c7 100644
--- a/src/composables/useDesktopState.test.ts
+++ b/src/composables/useDesktopState.test.ts
@@ -196,6 +196,31 @@ describe('filterGroupsByWorkspaceRoots', () => {
     ])
   })
 
+  it('maps durable pinned root paths to visible project names', () => {
+    const groups: UiProjectGroup[] = [
+      {
+        projectName: 'promo',
+        threads: [thread('promo-chat', '/tmp/promo')],
+      },
+      {
+        projectName: '.codex',
+        threads: [thread('codex-chat', '/Users/igor/.codex')],
+      },
+    ]
+    const rootsState: WorkspaceRootsState = {
+      order: ['/tmp/promo', '/Users/igor/.codex'],
+      labels: {},
+      active: ['/tmp/promo'],
+      projectOrder: ['/tmp/promo', '/Users/igor/.codex'],
+      pinnedProjectIds: ['/Users/igor/.codex'],
+    }
+
+    expect(filterGroupsByWorkspaceRoots(groups, rootsState).map((group) => group.projectName)).toEqual([
+      '.codex',
+      'promo',
+    ])
+  })
+
   it('keeps projectless groups stable when projects are pinned', () => {
     const groups: UiProjectGroup[] = [
       {
diff --git a/src/composables/useDesktopState.ts b/src/composables/useDesktopState.ts
index a5e192d3f..2d226ef31 100644
--- a/src/composables/useDesktopState.ts
+++ b/src/composables/useDesktopState.ts
@@ -1072,16 +1072,29 @@ function getWorkspaceProjectOrderNames(
 
 function getWorkspacePinnedProjectNames(
   rootsState: WorkspaceRootsState | null,
-  duplicateLeafNames: Set<string>,
+  groups: UiProjectGroup[],
 ): string[] {
   if (!rootsState) return []
   const remoteProjectsById = getRemoteProjectById(rootsState)
-  return (rootsState.pinnedProjectIds ?? []).map((projectId) => {
-    if (remoteProjectsById.has(projectId)) return projectId
+  const pinnedProjectNames: string[] = []
+  for (const projectId of rootsState.pinnedProjectIds ?? []) {
+    if (remoteProjectsById.has(projectId)) {
+      pinnedProjectNames.push(projectId)
+      continue
+    }
     const normalizedRootPath = normalizePathForUi(projectId).trim()
-    const leafName = toProjectNameFromWorkspaceRoot(normalizedRootPath)
-    return duplicateLeafNames.has(leafName) ? normalizedRootPath : leafName
-  }).filter((name) => name.length > 0)
+    if (!normalizedRootPath) continue
+    const matchedGroup = groups.find((group) => {
+      if (group.projectName === normalizedRootPath) return true
+      if (matchesWorkspaceRootProject(normalizedRootPath, group.projectName)) return true
+      return group.threads.some((thread) => normalizePathForUi(thread.cwd).trim() === normalizedRootPath)
+    })
+    const projectName = matchedGroup?.projectName ?? toProjectNameFromWorkspaceRoot(normalizedRootPath)
+    if (projectName && !pinnedProjectNames.includes(projectName)) {
+      pinnedProjectNames.push(projectName)
+    }
+  }
+  return pinnedProjectNames
 }
 
 function orderGroupsWithPinnedProjects(
@@ -1196,7 +1209,7 @@ function orderGroupsByWorkspaceProjectOrder(
   duplicateLeafNames: Set<string>,
 ): UiProjectGroup[] {
   const order = getWorkspaceProjectOrderNames(rootsState, duplicateLeafNames)
-  const pinnedProjectNames = getWorkspacePinnedProjectNames(rootsState, duplicateLeafNames)
+  const pinnedProjectNames = getWorkspacePinnedProjectNames(rootsState, groups)
   if (order.length === 0) return orderGroupsWithPinnedProjects(groups, pinnedProjectNames)
   const orderIndexByName = new Map(order.map((name, index) => [name, index]))
   const orderedGroups = [...groups].sort((first, second) => {
@@ -3979,8 +3992,7 @@ export function useDesktopState() {
 
   function applyThreadGroups(groups: UiProjectGroup[], rootsState: WorkspaceRootsState | null): void {
     const visibleGroups = filterGroupsByWorkspaceRoots(groups, rootsState)
-    const duplicateLeafNames = collectDuplicateProjectLeafNames(groups, rootsState)
-    pinnedProjectNames.value = getWorkspacePinnedProjectNames(rootsState, duplicateLeafNames)
+    pinnedProjectNames.value = getWorkspacePinnedProjectNames(rootsState, visibleGroups)
     const hasWorkspaceRootsState = Boolean(
       rootsState && (rootsState.order.length > 0 || rootsState.projectOrder.length > 0 || (rootsState.remoteProjects ?? []).length > 0),
     )
@@ -5139,8 +5151,7 @@ export function useDesktopState() {
   }
 
   function applyPinnedProjectNamesFromRootsState(rootsState: WorkspaceRootsState | null, groups: UiProjectGroup[] = sourceGroups.value): void {
-    const duplicateLeafNames = collectDuplicateProjectLeafNames(groups, rootsState)
-    pinnedProjectNames.value = getWorkspacePinnedProjectNames(rootsState, duplicateLeafNames)
+    pinnedProjectNames.value = getWorkspacePinnedProjectNames(rootsState, groups)
   }
 
   function isProjectPinned(projectName: string): boolean {

From c2927c220791887a0c2c389bbf9129dcfd31b826 Mon Sep 17 00:00:00 2001
From: Igor <igor.levochkin@xrtc.io>
Date: Sat, 9 May 2026 12:28:22 +0700
Subject: [PATCH 5/5] Restore pinned chats outside first thread page

---
 src/api/codexGateway.ts                      | 26 +++++++++++++++++++
 src/components/sidebar/SidebarThreadTree.vue | 25 ++++++++++++++----
 tests.md                                     | 27 ++++++++++++++++++++
 3 files changed, 73 insertions(+), 5 deletions(-)

diff --git a/src/api/codexGateway.ts b/src/api/codexGateway.ts
index 0cb3f0625..88ad3686b 100644
--- a/src/api/codexGateway.ts
+++ b/src/api/codexGateway.ts
@@ -50,6 +50,7 @@ import type {
   UiReviewWorkspaceView,
   UiRateLimitSnapshot,
   UiRateLimitWindow,
+  UiThread,
   UiThreadAutomation,
   UiThreadAutomationStatus,
 } from '../types/codex'
@@ -754,6 +755,31 @@ export async function getThreadGroupsPage(
   }
 }
 
+export async function getThreadSummariesByIds(threadIds: string[]): Promise<UiThread[]> {
+  const normalizedThreadIds = threadIds
+    .map((threadId) => threadId.trim())
+    .filter((threadId, index, rows) => threadId.length > 0 && rows.indexOf(threadId) === index)
+
+  if (normalizedThreadIds.length === 0) return []
+
+  const summaries = await Promise.all(
+    normalizedThreadIds.map(async (threadId) => {
+      try {
+        const payload = await callRpc<ThreadReadResponse>('thread/read', {
+          threadId,
+          includeTurns: false,
+        })
+        const groups = normalizeThreadGroupsV2({ data: [payload.thread] } as ThreadListResponse)
+        return groups.flatMap((group) => group.threads)[0] ?? null
+      } catch {
+        return null
+      }
+    }),
+  )
+
+  return summaries.filter((thread): thread is UiThread => thread !== null)
+}
+
 export function getBackgroundThreadListLimit(): number {
   return BACKGROUND_THREAD_LIST_LIMIT
 }
diff --git a/src/components/sidebar/SidebarThreadTree.vue b/src/components/sidebar/SidebarThreadTree.vue
index dc510b496..025977fab 100644
--- a/src/components/sidebar/SidebarThreadTree.vue
+++ b/src/components/sidebar/SidebarThreadTree.vue
@@ -809,6 +809,7 @@ import type { ComponentPublicInstance } from 'vue'
 import {
   deleteThreadAutomation,
   getPinnedThreadState,
+  getThreadSummariesByIds,
   getThreadAutomationMap,
   persistPinnedThreadIds,
   runThreadAutomationNow,
@@ -914,6 +915,7 @@ const showChatsFirst = ref(loadBooleanStorage(CHATS_FIRST_STORAGE_KEY, false))
 const chatSortMode = ref<ChatSortMode>(loadChatSortMode())
 let hasLoadedPinnedThreadState = false
 const pinnedThreadIds = ref<string[]>([])
+const pinnedThreadFallbackById = ref<Record<string, UiThread>>({})
 const inlineDeleteConfirmThreadId = ref('')
 const optimisticallyArchivedThreadIds = ref<string[]>([])
 const openProjectMenuId = ref('')
@@ -1155,6 +1157,11 @@ const hasHiddenChatThreads = computed(() => {
 const threadById = computed(() => {
   const map = new Map<string, UiThread>()
 
+  for (const thread of Object.values(pinnedThreadFallbackById.value)) {
+    if (optimisticallyArchivedThreadIdSet.value.has(thread.id)) continue
+    map.set(thread.id, thread)
+  }
+
   for (const group of props.groups) {
     for (const thread of group.threads) {
       if (optimisticallyArchivedThreadIdSet.value.has(thread.id)) continue
@@ -1173,11 +1180,18 @@ watch(
   },
 )
 
-watch(threadById, (threadsById) => {
-  const filtered = pinnedThreadIds.value.filter((threadId) => threadsById.has(threadId))
-  if (filtered.length === pinnedThreadIds.value.length) return
-  pinnedThreadIds.value = filtered
-})
+async function hydratePinnedThreadFallbacks(threadIds: string[]): Promise<void> {
+  const missingThreadIds = threadIds.filter((threadId) => !threadById.value.has(threadId))
+  if (missingThreadIds.length === 0) return
+
+  const threads = await getThreadSummariesByIds(missingThreadIds)
+  if (threads.length === 0) return
+
+  pinnedThreadFallbackById.value = {
+    ...pinnedThreadFallbackById.value,
+    ...Object.fromEntries(threads.map((thread) => [thread.id, thread])),
+  }
+}
 
 onMounted(async () => {
   const { threadIds } = await getPinnedThreadState()
@@ -1190,6 +1204,7 @@ onMounted(async () => {
 
   if (normalized.length > 0) {
     pinnedThreadIds.value = normalized
+    await hydratePinnedThreadFallbacks(normalized)
   }
   try {
     automationByThreadId.value = await getThreadAutomationMap()
diff --git a/tests.md b/tests.md
index 2f1de345e..0dfb49153 100644
--- a/tests.md
+++ b/tests.md
@@ -4956,3 +4956,30 @@ The sidebar Chats section lists the first 10 projectless chats, offers Show more
 
 #### Rollback/Cleanup
 - None.
+
+---
+
+### Pinned chats survive paginated thread list
+
+#### Feature/Change Name
+Pinned sidebar chats hydrate from their stored pinned ids even when they are older than the first `thread/list` page.
+
+#### Prerequisites/Setup
+1. Dev server running (`npm run dev -- --host 127.0.0.1 --port 5173` or equivalent)
+2. `.codex-global-state.json` contains `pinned-thread-ids` for chats that are not returned by the first recent `thread/list` page
+3. Light theme and dark theme both available from the appearance switcher
+
+#### Steps
+1. In light theme, open the app and expand the sidebar if it is collapsed.
+2. Confirm the `Pinned` section is visible above `Projects`.
+3. Confirm the pinned chat rows are visible even if those chat ids are absent from the first `thread/list` page.
+4. Refresh the browser tab and confirm the same pinned chat rows remain visible.
+5. Switch to dark theme and repeat steps 1-4.
+
+#### Expected Results
+- Stored pinned chat ids are not pruned just because they are absent from the current paginated thread list.
+- The sidebar hydrates missing pinned chat summaries and renders them in the `Pinned` section.
+- Pinned chat rows remain readable and selectable in light and dark themes.
+
+#### Rollback/Cleanup
+- None.