From 50047128018aeab6a49a3e57c19c98ac812b5a5e Mon Sep 17 00:00:00 2001
From: bashrusakh <bashrusakh@users.noreply.github.com>
Date: Wed, 15 Jul 2026 19:47:54 +1100
Subject: [PATCH 01/57] fix(sync): route directory-less todo updates

---
 packages/ui/src/sync/DOCUMENTATION.md         |  4 +
 .../__tests__/session-switch-resync.test.ts   | 83 ++++++++++++++++++-
 packages/ui/src/sync/event-reducer.ts         |  3 +
 packages/ui/src/sync/sync-context.tsx         | 18 +++-
 4 files changed, 101 insertions(+), 7 deletions(-)

diff --git a/packages/ui/src/sync/DOCUMENTATION.md b/packages/ui/src/sync/DOCUMENTATION.md
index 47a01834..9a021d60 100644
--- a/packages/ui/src/sync/DOCUMENTATION.md
+++ b/packages/ui/src/sync/DOCUMENTATION.md
@@ -168,6 +168,10 @@ Keep this in sync with `handleDirectoryEvent` in `sync-context.tsx`:
 | `question.asked/replied/rejected` | `question` |
 | `lsp.updated` | `lsp` |
 
+### Directory-less session events
+
+The global stream can omit a directory for a session-addressed event. Resolve it through the session routing index first. If the index is briefly stale during a session transition, route only when the event session matches the active session and that directory store exists; otherwise leave it un-routed rather than updating another directory.
+
 ## Adding a new event type
 
 1. Add the case to the event reducer (`event-reducer.ts`)
diff --git a/packages/ui/src/sync/__tests__/session-switch-resync.test.ts b/packages/ui/src/sync/__tests__/session-switch-resync.test.ts
index 7962067d..cd7ecd27 100644
--- a/packages/ui/src/sync/__tests__/session-switch-resync.test.ts
+++ b/packages/ui/src/sync/__tests__/session-switch-resync.test.ts
@@ -1,9 +1,10 @@
 import { describe, expect, test, beforeEach, mock } from "bun:test"
 import { create, type StoreApi } from "zustand"
-import type { PermissionRequest, QuestionRequest } from "@opencode-ai/sdk/v2/client"
+import type { Event, PermissionRequest, QuestionRequest } from "@opencode-ai/sdk/v2/client"
 
 const listPendingQuestionsCalls: Array<{ directories?: Array<string | null | undefined> }> = []
 const listPendingPermissionsCalls: Array<{ directories?: Array<string | null | undefined> }> = []
+const todoPersistWrites: Array<{ sessionID: string; todos: unknown }> = []
 let pendingQuestionsResponse: QuestionRequest[] = []
 let pendingPermissionsResponse: PermissionRequest[] = []
 let pendingQuestionsShouldThrow = false
@@ -41,7 +42,22 @@ mock.module("@/stores/useConfigStore", () => ({
 }))
 
 mock.module("@/stores/useTodosPersistStore", () => ({
-  useTodosPersistStore: { getState: () => ({}) },
+  useTodosPersistStore: {
+    getState: () => ({
+      setSessionTodos: (sessionID: string, todos: unknown) => {
+        todoPersistWrites.push({ sessionID, todos })
+      },
+    }),
+  },
+}))
+
+mock.module("sonner", () => ({
+  toast: {
+    dismiss: () => undefined,
+    error: () => undefined,
+    info: () => undefined,
+    success: () => undefined,
+  },
 }))
 
 mock.module("@/components/ui", () => ({
@@ -49,8 +65,13 @@ mock.module("@/components/ui", () => ({
 }))
 
 import { INITIAL_STATE, type State } from "../types"
-import type { DirectoryStore } from "../child-store"
-import { resyncBlockingRequestsForDirectory } from "../sync-context"
+import { ChildStoreManager, type DirectoryStore } from "../child-store"
+const {
+  createEventRoutingIndex,
+  handleEvent,
+  resyncBlockingRequestsForDirectory,
+  setActiveSession,
+} = await import("../sync-context")
 
 function buildQuestion(overrides: Partial<QuestionRequest> = {}): QuestionRequest {
   return {
@@ -91,6 +112,8 @@ describe("resyncBlockingRequestsForDirectory", () => {
     pendingPermissionsResponse = []
     pendingQuestionsShouldThrow = false
     pendingPermissionsShouldThrow = false
+    todoPersistWrites.length = 0
+    setActiveSession("", "")
   })
 
   test("calls listPendingQuestions and listPendingPermissions exactly once for the directory", async () => {
@@ -205,4 +228,56 @@ describe("resyncBlockingRequestsForDirectory", () => {
     expect(store.getState().question["ses_a"]?.[0]?.id).toBe("que_1")
     expect(listPendingPermissionsCalls).toHaveLength(1)
   })
+
+  test("routes a directory-less todo snapshot to its active session during a multi-store routing-index gap", () => {
+    const childStores = new ChildStoreManager()
+    const store = childStores.ensureChild("/target", { bootstrap: false })
+    childStores.ensureChild("/other", { bootstrap: false })
+    const todos = [
+      { content: "Finish plan", status: "completed", priority: "high" },
+      { content: "Implement changes", status: "in_progress", priority: "high" },
+    ]
+    const event = {
+      type: "todo.updated",
+      properties: { sessionID: "ses_a", todos },
+    } as Event
+    const routingIndex = createEventRoutingIndex()
+
+    expect(childStores.children.size).toBe(2)
+    expect(routingIndex.sessionDirectoryById.size).toBe(0)
+    for (const candidate of childStores.children.values()) {
+      const state = candidate.getState()
+      expect(state.session).toEqual([])
+      expect(state.message.ses_a).toBe(undefined)
+      expect(state.session_status.ses_a).toBe(undefined)
+    }
+
+    let storeWrites = 0
+    const unsubscribe = store.subscribe(() => {
+      storeWrites += 1
+    })
+    setActiveSession("/target", "ses_a")
+    handleEvent("global", event, childStores, routingIndex)
+
+    expect(store.getState().todo.ses_a).toEqual(todos)
+    expect(todoPersistWrites).toEqual([{ sessionID: "ses_a", todos }])
+    expect(storeWrites).toBe(1)
+
+    const stateAfterFirstSnapshot = store.getState()
+    const duplicateTodos = todos.map((todo) => ({ ...todo }))
+    const duplicateEvent = {
+      type: "todo.updated",
+      properties: { sessionID: "ses_a", todos: duplicateTodos },
+    } as Event
+    expect(duplicateTodos).not.toBe(todos)
+    expect(duplicateTodos).toEqual(todos)
+
+    handleEvent("global", duplicateEvent, childStores, routingIndex)
+
+    expect(store.getState()).toBe(stateAfterFirstSnapshot)
+    expect(todoPersistWrites).toEqual([{ sessionID: "ses_a", todos }])
+    expect(storeWrites).toBe(1)
+    unsubscribe()
+    childStores.disposeAll()
+  })
 })
diff --git a/packages/ui/src/sync/event-reducer.ts b/packages/ui/src/sync/event-reducer.ts
index 5288b140..884ce8c2 100644
--- a/packages/ui/src/sync/event-reducer.ts
+++ b/packages/ui/src/sync/event-reducer.ts
@@ -286,6 +286,9 @@ export function applyDirectoryEvent(
 
     case "todo.updated": {
       const props = event.properties as { sessionID: string; todos: Todo[] }
+      if (areJsonEquivalent(draft.todo[props.sessionID], props.todos)) {
+        return false
+      }
       draft.todo[props.sessionID] = props.todos
       callbacks?.onSetSessionTodo?.(props.sessionID, props.todos)
       return true
diff --git a/packages/ui/src/sync/sync-context.tsx b/packages/ui/src/sync/sync-context.tsx
index 0e5a301b..1e7c246b 100644
--- a/packages/ui/src/sync/sync-context.tsx
+++ b/packages/ui/src/sync/sync-context.tsx
@@ -606,7 +606,7 @@ const dispatchVSCodeRuntimeNotificationEvent = (directory: string, payload: Even
   }))
 }
 
-const createEventRoutingIndex = (): EventRoutingIndex => ({
+export const createEventRoutingIndex = (): EventRoutingIndex => ({
   sessionDirectoryById: new Map(),
   messageSessionById: new Map(),
   sessionMessageIdsById: new Map(),
@@ -896,8 +896,12 @@ const childStoreHasMessagePartState = (
   return Object.prototype.hasOwnProperty.call(store.getState().part, messageID)
 }
 
-const getActiveDirectoryFallback = (childStores: ChildStoreManager): string | null => {
+const getActiveDirectoryFallback = (
+  childStores: ChildStoreManager,
+  sessionID?: string | null,
+): string | null => {
   if (!_activeDirectory || !_activeSession) return null
+  if (sessionID && sessionID !== _activeSession) return null
   return childStores.getChild(_activeDirectory) ? _activeDirectory : null
 }
 
@@ -927,6 +931,14 @@ const resolveDirectoryFromRoutingIndex = (
     if (found) {
       return found
     }
+
+    // The global stream does not always include a directory. During a session
+    // transition, its routing index can lag the active session briefly; route
+    // a session-addressed event only when that session is the one being viewed.
+    const activeDirectory = getActiveDirectoryFallback(childStores, sessionID)
+    if (activeDirectory) {
+      return activeDirectory
+    }
   }
 
   const messageID = getMessageIdFromPayload(payload)
@@ -1351,7 +1363,7 @@ async function resyncDirectoryAfterReconnect(
   ingestDirectoryStateIntoRoutingIndex(routingIndex, directory, store.getState())
 }
 
-function handleEvent(
+export function handleEvent(
   rawDirectory: string,
   payload: Event,
   childStores: ChildStoreManager,

From 483ac6875ef47e9911aa14108b98a7511ca812e6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pascal=20Andr=C3=A9?= <pascalandr@gmail.com>
Date: Sun, 26 Jul 2026 17:53:19 +0200
Subject: [PATCH 02/57] fix(settings): persist collapsed message preference

---
 packages/web/server/lib/opencode/settings-helpers.js      | 3 +++
 packages/web/server/lib/opencode/settings-helpers.test.js | 8 ++++++++
 2 files changed, 11 insertions(+)

diff --git a/packages/web/server/lib/opencode/settings-helpers.js b/packages/web/server/lib/opencode/settings-helpers.js
index b95e1145..82aefd82 100644
--- a/packages/web/server/lib/opencode/settings-helpers.js
+++ b/packages/web/server/lib/opencode/settings-helpers.js
@@ -552,6 +552,9 @@ export const createSettingsHelpers = (dependencies) => {
         result.userMessageRenderingMode = mode;
       }
     }
+    if (typeof candidate.collapsibleUserMessages === 'boolean') {
+      result.collapsibleUserMessages = candidate.collapsibleUserMessages;
+    }
     if (typeof candidate.stickyUserHeader === 'boolean') {
       result.stickyUserHeader = candidate.stickyUserHeader;
     }
diff --git a/packages/web/server/lib/opencode/settings-helpers.test.js b/packages/web/server/lib/opencode/settings-helpers.test.js
index 20387b55..9ac08512 100644
--- a/packages/web/server/lib/opencode/settings-helpers.test.js
+++ b/packages/web/server/lib/opencode/settings-helpers.test.js
@@ -74,6 +74,14 @@ describe('settings helpers', () => {
     expect(helpers.sanitizeSettingsUpdate({ wideChatLayoutEnabled: 'true' })).toEqual({});
   });
 
+  it('accepts only booleans for collapsible user messages', () => {
+    const helpers = createTestHelpers();
+
+    expect(helpers.sanitizeSettingsUpdate({ collapsibleUserMessages: true })).toEqual({ collapsibleUserMessages: true });
+    expect(helpers.sanitizeSettingsUpdate({ collapsibleUserMessages: false })).toEqual({ collapsibleUserMessages: false });
+    expect(helpers.sanitizeSettingsUpdate({ collapsibleUserMessages: 'true' })).toEqual({});
+  });
+
   it('accepts messageStreamTransport as a persisted shared setting', () => {
     const helpers = createTestHelpers();
 

From abb396e080d7eda0afb103a8ca2584e271ae667c Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Tue, 4 Aug 2026 11:29:58 +0000
Subject: [PATCH 03/57] fix(walkthrough): block unauthenticated providers with
 a friendly refusal

When the walkthrough small model resolves to a provider with no usable
login, readiness was still ready and generate returned a raw 500 message.
Refuse up front with no-provider-login and surface a blocker instead.

Closes openchamber/openchamber#2607

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>
---
 .../views/walkthrough/WalkthroughBlocker.tsx  |   9 +-
 .../views/walkthrough/WalkthroughView.tsx     |   1 +
 packages/ui/src/lib/i18n/messages/de.ts       |   3 +
 packages/ui/src/lib/i18n/messages/en.ts       |   3 +
 packages/ui/src/lib/i18n/messages/es.ts       |   3 +
 packages/ui/src/lib/i18n/messages/fr.ts       |   3 +
 packages/ui/src/lib/i18n/messages/ja.ts       |   3 +
 packages/ui/src/lib/i18n/messages/ko.ts       |   3 +
 packages/ui/src/lib/i18n/messages/pl.ts       |   3 +
 packages/ui/src/lib/i18n/messages/pt-BR.ts    |   3 +
 packages/ui/src/lib/i18n/messages/uk.ts       |   3 +
 packages/ui/src/lib/i18n/messages/zh-CN.ts    |   3 +
 packages/ui/src/lib/i18n/messages/zh-TW.ts    |   3 +
 packages/ui/src/lib/walkthrough/types.ts      |   1 +
 .../server/lib/small-model/DOCUMENTATION.md   |  15 +-
 packages/web/server/lib/small-model/call.js   |  22 ++-
 .../web/server/lib/small-model/call.test.js   |  11 +-
 packages/web/server/lib/small-model/index.js  |  11 +-
 .../web/server/lib/small-model/index.test.js  |  21 ++-
 .../server/lib/walkthrough/DOCUMENTATION.md   |   7 +
 packages/web/server/lib/walkthrough/index.js  |  16 ++
 .../lib/walkthrough/reproduce-2607.test.js    | 151 ++++++++++++++++++
 22 files changed, 286 insertions(+), 12 deletions(-)
 create mode 100644 packages/web/server/lib/walkthrough/reproduce-2607.test.js

diff --git a/packages/ui/src/components/views/walkthrough/WalkthroughBlocker.tsx b/packages/ui/src/components/views/walkthrough/WalkthroughBlocker.tsx
index 2f0af021..f23696be 100644
--- a/packages/ui/src/components/views/walkthrough/WalkthroughBlocker.tsx
+++ b/packages/ui/src/components/views/walkthrough/WalkthroughBlocker.tsx
@@ -41,7 +41,8 @@ export const WalkthroughBlocker = ({
   // Settings.
   const canChooseModel = reason === 'context-too-small'
     || reason === 'structured-output-unsupported'
-    || reason === 'output-exhausted';
+    || reason === 'output-exhausted'
+    || reason === 'no-provider-login';
 
   useEffect(() => {
     if (!canChooseModel || providers !== undefined) return;
@@ -100,6 +101,11 @@ export const WalkthroughBlocker = ({
 
   const description = () => {
     if (reason === 'no-model') return t('walkthrough.blocked.noModel.description');
+    if (reason === 'no-provider-login') {
+      return label
+        ? t('walkthrough.blocked.noProviderLogin.description', { model: label })
+        : t('walkthrough.blocked.noProviderLogin.descriptionUnknownModel');
+    }
     if (reason === 'empty-diff') return t('walkthrough.blocked.emptyDiff.description');
     if (reason === 'only-generated') return t('walkthrough.blocked.onlyGenerated.description');
     if (reason === 'output-exhausted') {
@@ -123,6 +129,7 @@ export const WalkthroughBlocker = ({
 
   const title = () => {
     if (reason === 'no-model') return t('walkthrough.blocked.noModel.title');
+    if (reason === 'no-provider-login') return t('walkthrough.blocked.noProviderLogin.title');
     if (reason === 'empty-diff') return t('walkthrough.blocked.emptyDiff.title');
     if (reason === 'only-generated') return t('walkthrough.blocked.onlyGenerated.title');
     if (reason === 'output-exhausted') return t('walkthrough.blocked.outputExhausted.title');
diff --git a/packages/ui/src/components/views/walkthrough/WalkthroughView.tsx b/packages/ui/src/components/views/walkthrough/WalkthroughView.tsx
index c0403b75..15b9baa8 100644
--- a/packages/ui/src/components/views/walkthrough/WalkthroughView.tsx
+++ b/packages/ui/src/components/views/walkthrough/WalkthroughView.tsx
@@ -406,6 +406,7 @@ export const WalkthroughView = ({ directory }: WalkthroughViewProps) => {
   const blockedReason = entry.error?.code === 'context-too-small'
     || entry.error?.code === 'structured-output-unsupported'
     || entry.error?.code === 'no-model'
+    || entry.error?.code === 'no-provider-login'
     || entry.error?.code === 'empty-diff'
     || entry.error?.code === 'only-generated'
     || entry.error?.code === 'output-exhausted'
diff --git a/packages/ui/src/lib/i18n/messages/de.ts b/packages/ui/src/lib/i18n/messages/de.ts
index 0db76c86..4f353026 100644
--- a/packages/ui/src/lib/i18n/messages/de.ts
+++ b/packages/ui/src/lib/i18n/messages/de.ts
@@ -2866,6 +2866,9 @@ export const dict = {
   'walkthrough.importance.context': 'Kontext',
   'walkthrough.blocked.noModel.title': 'Kein Modell ausgewählt',
   'walkthrough.blocked.noModel.description': 'Wählen Sie zuerst ein Modell aus.',
+  'walkthrough.blocked.noProviderLogin.title': 'Dieser Anbieter ist nicht angemeldet',
+  'walkthrough.blocked.noProviderLogin.description': '{model} braucht eine Anmeldung bei seinem Anbieter. Melde dich an oder wähle ein Modell eines Anbieters, den du bereits nutzt.',
+  'walkthrough.blocked.noProviderLogin.descriptionUnknownModel': 'Das ausgewählte Modell braucht eine Anmeldung bei seinem Anbieter. Melde dich an oder wähle ein Modell eines Anbieters, den du bereits nutzt.',
   'walkthrough.blocked.emptyDiff.title': 'Kein Diff vorhanden',
   'walkthrough.blocked.emptyDiff.description': 'Es gibt keine Änderungen, die zusammengefasst werden können.',
   'walkthrough.blocked.contextTooSmall.title': 'Kontext zu klein',
diff --git a/packages/ui/src/lib/i18n/messages/en.ts b/packages/ui/src/lib/i18n/messages/en.ts
index 17d137e5..53929a2f 100644
--- a/packages/ui/src/lib/i18n/messages/en.ts
+++ b/packages/ui/src/lib/i18n/messages/en.ts
@@ -1147,6 +1147,9 @@ export const dict = {
   'walkthrough.importance.context': 'Context',
   'walkthrough.blocked.noModel.title': 'No small model available',
   'walkthrough.blocked.noModel.description': 'Sign in to a model provider to generate a review.',
+  'walkthrough.blocked.noProviderLogin.title': 'This provider is not signed in',
+  'walkthrough.blocked.noProviderLogin.description': '{model} needs a login for its provider. Sign in, or choose a model from a provider you already use.',
+  'walkthrough.blocked.noProviderLogin.descriptionUnknownModel': 'The selected model needs a login for its provider. Sign in, or choose a model from a provider you already use.',
   'walkthrough.blocked.emptyDiff.title': 'Nothing to review',
   'walkthrough.blocked.emptyDiff.description': 'There are no changes in this scope yet.',
   'walkthrough.blocked.contextTooSmall.title': 'This diff is too large for the current model',
diff --git a/packages/ui/src/lib/i18n/messages/es.ts b/packages/ui/src/lib/i18n/messages/es.ts
index ea5086d0..140e686e 100644
--- a/packages/ui/src/lib/i18n/messages/es.ts
+++ b/packages/ui/src/lib/i18n/messages/es.ts
@@ -1148,6 +1148,9 @@ export const dict: Record<I18nKey, string> = {
   "walkthrough.importance.context": "Contexto",
   "walkthrough.blocked.noModel.title": "No hay ningún modelo pequeño disponible",
   "walkthrough.blocked.noModel.description": "Inicia sesión en un proveedor de modelos para generar una revisión.",
+  "walkthrough.blocked.noProviderLogin.title": "Este proveedor no tiene sesión iniciada",
+  "walkthrough.blocked.noProviderLogin.description": "{model} necesita un inicio de sesión en su proveedor. Inicia sesión o elige un modelo de un proveedor que ya uses.",
+  "walkthrough.blocked.noProviderLogin.descriptionUnknownModel": "El modelo seleccionado necesita un inicio de sesión en su proveedor. Inicia sesión o elige un modelo de un proveedor que ya uses.",
   "walkthrough.blocked.emptyDiff.title": "Nada que revisar",
   "walkthrough.blocked.emptyDiff.description": "Todavía no hay cambios en este ámbito.",
   "walkthrough.blocked.contextTooSmall.title": "Este diff es demasiado grande para el modelo actual",
diff --git a/packages/ui/src/lib/i18n/messages/fr.ts b/packages/ui/src/lib/i18n/messages/fr.ts
index 3a625450..479033dc 100644
--- a/packages/ui/src/lib/i18n/messages/fr.ts
+++ b/packages/ui/src/lib/i18n/messages/fr.ts
@@ -972,6 +972,9 @@ export const dict = {
   'walkthrough.importance.context': 'Contexte',
   'walkthrough.blocked.noModel.title': 'Aucun petit modèle disponible',
   'walkthrough.blocked.noModel.description': 'Connectez-vous à un fournisseur de modèles pour générer une revue.',
+  'walkthrough.blocked.noProviderLogin.title': 'Ce fournisseur n’est pas connecté',
+  'walkthrough.blocked.noProviderLogin.description': '{model} nécessite une connexion à son fournisseur. Connectez-vous, ou choisissez un modèle d’un fournisseur que vous utilisez déjà.',
+  'walkthrough.blocked.noProviderLogin.descriptionUnknownModel': 'Le modèle sélectionné nécessite une connexion à son fournisseur. Connectez-vous, ou choisissez un modèle d’un fournisseur que vous utilisez déjà.',
   'walkthrough.blocked.emptyDiff.title': 'Rien à examiner',
   'walkthrough.blocked.emptyDiff.description': 'Il n’y a encore aucune modification dans cette portée.',
   'walkthrough.blocked.contextTooSmall.title': 'Ce diff est trop volumineux pour le modèle actuel',
diff --git a/packages/ui/src/lib/i18n/messages/ja.ts b/packages/ui/src/lib/i18n/messages/ja.ts
index 181ec3e9..ed810851 100644
--- a/packages/ui/src/lib/i18n/messages/ja.ts
+++ b/packages/ui/src/lib/i18n/messages/ja.ts
@@ -1144,6 +1144,9 @@ export const dict: Record<I18nKey, string> = {
   'walkthrough.importance.context': '補足',
   'walkthrough.blocked.noModel.title': '利用できるスモールモデルがありません',
   'walkthrough.blocked.noModel.description': 'レビューを生成するにはモデルプロバイダーにサインインしてください。',
+  'walkthrough.blocked.noProviderLogin.title': 'このプロバイダーにはサインインしていません',
+  'walkthrough.blocked.noProviderLogin.description': '{model} にはプロバイダーへのログインが必要です。サインインするか、すでに使っているプロバイダーのモデルを選んでください。',
+  'walkthrough.blocked.noProviderLogin.descriptionUnknownModel': '選択したモデルにはプロバイダーへのログインが必要です。サインインするか、すでに使っているプロバイダーのモデルを選んでください。',
   'walkthrough.blocked.emptyDiff.title': 'レビュー対象がありません',
   'walkthrough.blocked.emptyDiff.description': 'この範囲にはまだ変更がありません。',
   'walkthrough.blocked.contextTooSmall.title': 'この差分は現在のモデルには大きすぎます',
diff --git a/packages/ui/src/lib/i18n/messages/ko.ts b/packages/ui/src/lib/i18n/messages/ko.ts
index 150a56ce..d9d68816 100644
--- a/packages/ui/src/lib/i18n/messages/ko.ts
+++ b/packages/ui/src/lib/i18n/messages/ko.ts
@@ -1148,6 +1148,9 @@ export const dict: Record<I18nKey, string> = {
   'walkthrough.importance.context': '참고',
   'walkthrough.blocked.noModel.title': '사용할 수 있는 스몰 모델이 없습니다',
   'walkthrough.blocked.noModel.description': '리뷰를 생성하려면 모델 제공자에 로그인하세요.',
+  'walkthrough.blocked.noProviderLogin.title': '이 제공자에 로그인되어 있지 않습니다',
+  'walkthrough.blocked.noProviderLogin.description': '{model}을(를) 쓰려면 해당 제공자에 로그인해야 합니다. 로그인하거나, 이미 사용 중인 제공자의 모델을 선택하세요.',
+  'walkthrough.blocked.noProviderLogin.descriptionUnknownModel': '선택한 모델을 쓰려면 해당 제공자에 로그인해야 합니다. 로그인하거나, 이미 사용 중인 제공자의 모델을 선택하세요.',
   'walkthrough.blocked.emptyDiff.title': '리뷰할 내용이 없습니다',
   'walkthrough.blocked.emptyDiff.description': '이 범위에는 아직 변경 사항이 없습니다.',
   'walkthrough.blocked.contextTooSmall.title': '이 diff는 현재 모델에 너무 큽니다',
diff --git a/packages/ui/src/lib/i18n/messages/pl.ts b/packages/ui/src/lib/i18n/messages/pl.ts
index 8f93e1f6..949b745f 100644
--- a/packages/ui/src/lib/i18n/messages/pl.ts
+++ b/packages/ui/src/lib/i18n/messages/pl.ts
@@ -1460,6 +1460,9 @@ export const dict: Record<I18nKey, string> = {
   'walkthrough.importance.context': 'Kontekst',
   'walkthrough.blocked.noModel.title': 'Brak dostępnego małego modelu',
   'walkthrough.blocked.noModel.description': 'Zaloguj się u dostawcy modeli, aby wygenerować przegląd.',
+  'walkthrough.blocked.noProviderLogin.title': 'Ten dostawca nie jest zalogowany',
+  'walkthrough.blocked.noProviderLogin.description': '{model} wymaga logowania u swojego dostawcy. Zaloguj się albo wybierz model u dostawcy, którego już używasz.',
+  'walkthrough.blocked.noProviderLogin.descriptionUnknownModel': 'Wybrany model wymaga logowania u swojego dostawcy. Zaloguj się albo wybierz model u dostawcy, którego już używasz.',
   'walkthrough.blocked.emptyDiff.title': 'Nie ma czego przeglądać',
   'walkthrough.blocked.emptyDiff.description': 'W tym zakresie nie ma jeszcze zmian.',
   'walkthrough.blocked.contextTooSmall.title': 'Te różnice są za duże dla bieżącego modelu',
diff --git a/packages/ui/src/lib/i18n/messages/pt-BR.ts b/packages/ui/src/lib/i18n/messages/pt-BR.ts
index 44fef67a..6c79996a 100644
--- a/packages/ui/src/lib/i18n/messages/pt-BR.ts
+++ b/packages/ui/src/lib/i18n/messages/pt-BR.ts
@@ -1148,6 +1148,9 @@ export const dict: Record<I18nKey, string> = {
   "walkthrough.importance.context": "Contexto",
   "walkthrough.blocked.noModel.title": "Nenhum modelo pequeno disponível",
   "walkthrough.blocked.noModel.description": "Entre em um provedor de modelos para gerar uma revisão.",
+  "walkthrough.blocked.noProviderLogin.title": "Este provedor não está conectado",
+  "walkthrough.blocked.noProviderLogin.description": "{model} precisa de login no provedor. Entre na conta ou escolha um modelo de um provedor que você já usa.",
+  "walkthrough.blocked.noProviderLogin.descriptionUnknownModel": "O modelo selecionado precisa de login no provedor. Entre na conta ou escolha um modelo de um provedor que você já usa.",
   "walkthrough.blocked.emptyDiff.title": "Nada para revisar",
   "walkthrough.blocked.emptyDiff.description": "Ainda não há mudanças neste escopo.",
   "walkthrough.blocked.contextTooSmall.title": "Este diff é grande demais para o modelo atual",
diff --git a/packages/ui/src/lib/i18n/messages/uk.ts b/packages/ui/src/lib/i18n/messages/uk.ts
index c8663cea..6005df66 100644
--- a/packages/ui/src/lib/i18n/messages/uk.ts
+++ b/packages/ui/src/lib/i18n/messages/uk.ts
@@ -1148,6 +1148,9 @@ export const dict: Record<I18nKey, string> = {
   "walkthrough.importance.context": "Контекст",
   "walkthrough.blocked.noModel.title": "Немає доступної small model",
   "walkthrough.blocked.noModel.description": "Увійдіть до провайдера моделей, щоб створити розбір.",
+  "walkthrough.blocked.noProviderLogin.title": "У цей провайдер не ввійшли",
+  "walkthrough.blocked.noProviderLogin.description": "{model} потребує входу в його провайдер. Увійдіть або виберіть модель у провайдера, яким ви вже користуєтесь.",
+  "walkthrough.blocked.noProviderLogin.descriptionUnknownModel": "Вибрана модель потребує входу в її провайдер. Увійдіть або виберіть модель у провайдера, яким ви вже користуєтесь.",
   "walkthrough.blocked.emptyDiff.title": "Немає що оглядати",
   "walkthrough.blocked.emptyDiff.description": "У цій області поки що немає змін.",
   "walkthrough.blocked.contextTooSmall.title": "Цей diff завеликий для поточної моделі",
diff --git a/packages/ui/src/lib/i18n/messages/zh-CN.ts b/packages/ui/src/lib/i18n/messages/zh-CN.ts
index 76ffac2f..551b95cf 100644
--- a/packages/ui/src/lib/i18n/messages/zh-CN.ts
+++ b/packages/ui/src/lib/i18n/messages/zh-CN.ts
@@ -1148,6 +1148,9 @@ export const dict: Record<I18nKey, string> = {
   'walkthrough.importance.context': '背景',
   'walkthrough.blocked.noModel.title': '没有可用的小模型',
   'walkthrough.blocked.noModel.description': '请登录模型提供方后再生成评审。',
+  'walkthrough.blocked.noProviderLogin.title': '尚未登录此提供方',
+  'walkthrough.blocked.noProviderLogin.description': '{model} 需要登录其提供方。请先登录，或改选你已在使用的提供方中的模型。',
+  'walkthrough.blocked.noProviderLogin.descriptionUnknownModel': '所选模型需要登录其提供方。请先登录，或改选你已在使用的提供方中的模型。',
   'walkthrough.blocked.emptyDiff.title': '没有可评审的内容',
   'walkthrough.blocked.emptyDiff.description': '该范围内暂无改动。',
   'walkthrough.blocked.contextTooSmall.title': '当前模型无法容纳这份差异',
diff --git a/packages/ui/src/lib/i18n/messages/zh-TW.ts b/packages/ui/src/lib/i18n/messages/zh-TW.ts
index 3538d59c..95b0af8b 100644
--- a/packages/ui/src/lib/i18n/messages/zh-TW.ts
+++ b/packages/ui/src/lib/i18n/messages/zh-TW.ts
@@ -1160,6 +1160,9 @@ export const dict: Record<I18nKey, string> = {
   'walkthrough.importance.context': '背景',
   'walkthrough.blocked.noModel.title': '沒有可用的小模型',
   'walkthrough.blocked.noModel.description': '請先登入模型供應商再產生審閱。',
+  'walkthrough.blocked.noProviderLogin.title': '尚未登入此供應商',
+  'walkthrough.blocked.noProviderLogin.description': '{model} 需要登入其供應商。請先登入，或改選你已在使用的供應商中的模型。',
+  'walkthrough.blocked.noProviderLogin.descriptionUnknownModel': '所選模型需要登入其供應商。請先登入，或改選你已在使用的供應商中的模型。',
   'walkthrough.blocked.emptyDiff.title': '沒有可審閱的內容',
   'walkthrough.blocked.emptyDiff.description': '此範圍目前沒有變更。',
   'walkthrough.blocked.contextTooSmall.title': '目前模型無法容納這份差異',
diff --git a/packages/ui/src/lib/walkthrough/types.ts b/packages/ui/src/lib/walkthrough/types.ts
index 8c6b5a23..40bfd62e 100644
--- a/packages/ui/src/lib/walkthrough/types.ts
+++ b/packages/ui/src/lib/walkthrough/types.ts
@@ -91,6 +91,7 @@ export type WalkthroughStage = 'collecting' | 'asking' | 'retrying' | 'assemblin
 
 export type WalkthroughBlockedReason =
   | 'no-model'
+  | 'no-provider-login'
   | 'empty-diff'
   | 'only-generated'
   | 'context-too-small'
diff --git a/packages/web/server/lib/small-model/DOCUMENTATION.md b/packages/web/server/lib/small-model/DOCUMENTATION.md
index a9d60a99..1776f1e1 100644
--- a/packages/web/server/lib/small-model/DOCUMENTATION.md
+++ b/packages/web/server/lib/small-model/DOCUMENTATION.md
@@ -69,10 +69,17 @@ other runtime API.
 - `timeoutMs` overrides the 60s default per call; `signal` lets a caller abort
   a request that is no longer wanted. Both apply to every wire format.
 - `describeSmallModel()` additionally reports `inputCharBudget`,
-  `contextTokens`, `contextKnown`, and `structuredOutput`. The last is
-  tri-state: `true`/`false` from the catalog, `null` when the catalog omits the
-  field — which it does for roughly half of all models, aggregators and proxies
-  especially. Callers must treat `null` as "try it", not "unsupported".
+  `contextTokens`, `contextKnown`, `structuredOutput`, and `hasLogin`. The last
+  is whether the resolved provider has a usable credential (`auth.json` or
+  config `provider.<id>.options.apiKey`) — settings/config overrides can name a
+  provider with none, and callers such as the walkthrough refuse before the
+  request. `structuredOutput` is tri-state: `true`/`false` from the catalog,
+  `null` when the catalog omits the field — which it does for roughly half of
+  all models, aggregators and proxies especially. Callers must treat `null` as
+  "try it", not "unsupported".
+- Missing credentials throw with `statusCode: 401` and
+  `code: 'no-provider-login'` rather than a bare `Error`, so UI callers can show
+  a blocker instead of a raw 500 message.
 - `call.js` — wire formats and per-provider auth, replicating OpenCode's
   plugin auth loaders:
   - **GitHub Copilot**: fetches the requested model's authenticated `/models`
diff --git a/packages/web/server/lib/small-model/call.js b/packages/web/server/lib/small-model/call.js
index 17c8949c..c3a090a1 100644
--- a/packages/web/server/lib/small-model/call.js
+++ b/packages/web/server/lib/small-model/call.js
@@ -566,15 +566,31 @@ const readProviderConfig = (workingDirectory, providerID) => {
 // Dispatch
 // ---------------------------------------------------------------------------
 
+/**
+ * Same credential resolution the request path uses: config
+ * `provider.<id>.options.apiKey` wins, then the auth.json entry.
+ * Callers that need to refuse before spending a request (walkthrough readiness)
+ * must use this rather than inventing a second rule.
+ */
+export function resolveProviderLogin({ auth, workingDirectory, providerID }) {
+  const providerConfig = readProviderConfig(workingDirectory, providerID);
+  return providerConfig?.auth || getAuthEntryForProvider(auth, providerID) || null;
+}
+
 export async function callSmallModel({ auth, catalog, workingDirectory, providerID, modelID, prompt, system, maxOutputTokens, responseSchema, timeoutMs, signal }) {
   const tokens = Number(maxOutputTokens) > 0 ? Number(maxOutputTokens) : DEFAULT_MAX_OUTPUT_TOKENS;
   const providerConfig = readProviderConfig(workingDirectory, providerID);
   // Match OpenCode's resolveSDK precedence:
-  // config provider.<id>.options.apiKey (providerConfig.auth) wins; the
-  // auth.json entry is only a fallback.
+  // config provider.<id>.options.apiKey wins; the auth.json entry is only a fallback.
   const entry = providerConfig?.auth || getAuthEntryForProvider(auth, providerID);
   if (!entry) {
-    throw new Error(`No OpenCode login found for provider "${providerID}"`);
+    // Structured so the walkthrough (and any other caller) can show a blocker
+    // instead of a raw 500 banner with this developer-oriented sentence.
+    throw Object.assign(new Error(`No OpenCode login found for provider "${providerID}"`), {
+      statusCode: 401,
+      code: 'no-provider-login',
+      providerID,
+    });
   }
 
   if (providerID === 'github-copilot') {
diff --git a/packages/web/server/lib/small-model/call.test.js b/packages/web/server/lib/small-model/call.test.js
index 78ef733f..154fd986 100644
--- a/packages/web/server/lib/small-model/call.test.js
+++ b/packages/web/server/lib/small-model/call.test.js
@@ -171,14 +171,21 @@ describe('callSmallModel — custom provider config', () => {
         provider: { custom: { options: { baseURL: 'https://proxy.example.test/v1' } } },
       });
 
-      await expect(callSmallModel({
+      const error = await callSmallModel({
         auth: {},
         catalog: {},
         workingDirectory: '/proj',
         providerID: 'custom',
         modelID: 'gpt-4o-mini',
         prompt: 'hi',
-      })).rejects.toThrow('No OpenCode login found for provider "custom"');
+      }).then(() => null, (e) => e);
+
+      expect(error).toMatchObject({
+        message: 'No OpenCode login found for provider "custom"',
+        code: 'no-provider-login',
+        statusCode: 401,
+        providerID: 'custom',
+      });
 
       // The credential gate fires before any network call.
       expect(fetchMock).not.toHaveBeenCalled();
diff --git a/packages/web/server/lib/small-model/index.js b/packages/web/server/lib/small-model/index.js
index 40e5e7f5..955797e6 100644
--- a/packages/web/server/lib/small-model/index.js
+++ b/packages/web/server/lib/small-model/index.js
@@ -5,7 +5,7 @@ import { readAuthFile } from '../opencode/auth.js';
 import { readConfigLayers } from '../opencode/shared.js';
 import { getModelCatalog } from './catalog.js';
 import { resolveSmallModel, parseModelRef, isUsableAuthEntry, getAuthEntryForProvider } from './resolve.js';
-import { callSmallModel } from './call.js';
+import { callSmallModel, resolveProviderLogin } from './call.js';
 
 const OPENCHAMBER_SETTINGS_FILE = path.join(
   process.env.OPENCHAMBER_DATA_DIR
@@ -252,8 +252,17 @@ export async function describeSmallModel({ directory, preferredProviderID, prefe
     outputReserveTokens: reserveTokens,
   });
 
+  // Settings/config/request overrides can name a provider with no usable login.
+  // Report that here so readiness can refuse before the user pays for a 401.
+  const hasLogin = Boolean(resolveProviderLogin({
+    auth,
+    workingDirectory: directory,
+    providerID: resolved.providerID,
+  }));
+
   return {
     ...resolved,
+    hasLogin,
     inputCharBudget: maxChars,
     contextTokens,
     contextKnown,
diff --git a/packages/web/server/lib/small-model/index.test.js b/packages/web/server/lib/small-model/index.test.js
index 14e5f015..fc5d741c 100644
--- a/packages/web/server/lib/small-model/index.test.js
+++ b/packages/web/server/lib/small-model/index.test.js
@@ -18,7 +18,13 @@ vi.mock('./catalog.js', () => ({
   getModelCatalog: vi.fn(),
   getCatalogProvider: vi.fn(),
 }));
-vi.mock('./call.js', () => ({ callSmallModel: vi.fn() }));
+vi.mock('./call.js', () => ({
+  callSmallModel: vi.fn(),
+  resolveProviderLogin: vi.fn(({ auth, providerID }) => {
+    const entry = auth?.[providerID];
+    return entry && typeof entry === 'object' ? entry : null;
+  }),
+}));
 
 const { generateSmallModelText, describeSmallModel } = await import('./index.js');
 const { readAuthFile } = await import('../opencode/auth.js');
@@ -126,6 +132,19 @@ describe('describeSmallModel — capability reporting', () => {
       contextTokens: 8_000,
       contextKnown: true,
       structuredOutput: true,
+      hasLogin: true,
+    });
+  });
+
+  it('reports hasLogin false when the resolved provider has no usable credential', async () => {
+    readAuthFile.mockReturnValue({});
+
+    const described = await describeSmallModel({ directory: '/proj' });
+
+    expect(described).toMatchObject({
+      providerID: 'anthropic',
+      modelID: 'claude-haiku-4-5',
+      hasLogin: false,
     });
   });
 
diff --git a/packages/web/server/lib/walkthrough/DOCUMENTATION.md b/packages/web/server/lib/walkthrough/DOCUMENTATION.md
index 43d59d16..63997184 100644
--- a/packages/web/server/lib/walkthrough/DOCUMENTATION.md
+++ b/packages/web/server/lib/walkthrough/DOCUMENTATION.md
@@ -118,6 +118,13 @@ model picker, only shows providers with a usable login. The in-panel picker on a
 blocked walkthrough writes this setting too, so recovering from a refusal never
 silently changes the model behind commit messages.
 
+A settings or `opencode.json` `small_model` override can still name a provider
+with no usable login (neither `auth.json` nor `provider.<id>.options.apiKey`).
+`describeSmallModel` reports that as `hasLogin: false`, readiness refuses with
+`code: 'no-provider-login'`, and generation maps the same code to HTTP 401 —
+so the panel shows a blocker with a model picker instead of looking ready and
+then dumping the raw `No OpenCode login found for provider "…"` string.
+
 ## Output language
 
 A walkthrough its reader cannot read is worth nothing, so the prose language is
diff --git a/packages/web/server/lib/walkthrough/index.js b/packages/web/server/lib/walkthrough/index.js
index 600b8af4..057a2c58 100644
--- a/packages/web/server/lib/walkthrough/index.js
+++ b/packages/web/server/lib/walkthrough/index.js
@@ -333,6 +333,12 @@ function computeReadiness({ model, digest, files, fileCount, hunkCount, generate
     return { ready: false, reason, model, generatedFileCount };
   }
 
+  // A resolved override/config model can still have no usable login. Refuse up
+  // front so the panel does not look ready and then dump a raw auth error.
+  if (model.hasLogin === false) {
+    return { ready: false, reason: 'no-provider-login', model };
+  }
+
   // Built with the same language the generation would use: the instruction is
   // part of the prompt, so a readiness answer computed without it would be
   // measuring a request nobody is going to send.
@@ -392,6 +398,13 @@ async function runGeneration({ directory, source, repoRoot, key, force, explicit
   if (!model) {
     throw fail('No model is available — sign in to a provider first', 404, { code: 'no-model' });
   }
+  if (model.hasLogin === false) {
+    throw fail(
+      `No OpenCode login found for provider "${model.providerID}" — sign in or choose a different model`,
+      401,
+      { code: 'no-provider-login', model },
+    );
+  }
 
   const { digest, files, idByAlias, fileCount, hunkCount, generatedFileCount } = await loadCurrentDiff(directory, source, deps);
   setStage(repoRoot, key, 'asking');
@@ -494,6 +507,9 @@ async function runGeneration({ directory, source, repoRoot, key, force, explicit
     if (error?.code === 'output-exhausted') {
       return fail(error.message, 409, { code: 'output-exhausted', model });
     }
+    if (error?.code === 'no-provider-login') {
+      return fail(error.message, 401, { code: 'no-provider-login', model });
+    }
     return null;
   };
 
diff --git a/packages/web/server/lib/walkthrough/reproduce-2607.test.js b/packages/web/server/lib/walkthrough/reproduce-2607.test.js
new file mode 100644
index 00000000..7ef6c15c
--- /dev/null
+++ b/packages/web/server/lib/walkthrough/reproduce-2607.test.js
@@ -0,0 +1,151 @@
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import express from 'express';
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+
+// ---------------------------------------------------------------------------
+// Regression for https://github.com/openchamber/openchamber/issues/2607
+// "[Bug] Why say so?" (walkthrough panel)
+//
+// Before the fix, a walkthrough small model whose provider had no usable login
+// reported readiness ready:true, then generation returned HTTP 500 with the raw
+// message `No OpenCode login found for provider "deepseek"` — shown in the
+// error banner above the "No walkthrough yet" empty state.
+//
+// After the fix: readiness refuses with `no-provider-login`, and generation
+// answers 401 with the same structured code so the UI can show a blocker.
+// ---------------------------------------------------------------------------
+
+const TEMP_HOME = fs.mkdtempSync(path.join(os.tmpdir(), 'oc-home-2607-'));
+process.env.HOME = TEMP_HOME;
+process.env.OPENCHAMBER_DATA_DIR = path.join(TEMP_HOME, '.config', 'openchamber');
+
+const CATALOG = {
+  deepseek: {
+    id: 'deepseek',
+    name: 'DeepSeek',
+    api: 'https://api.deepseek.com',
+    models: {
+      'deepseek-v4-flash': {
+        id: 'deepseek-v4-flash',
+        name: 'DeepSeek V4 Flash',
+        family: 'deepseek-flash',
+        limit: { context: 128_000 },
+      },
+    },
+  },
+};
+
+vi.mock('../../opencode/models-metadata.js', () => ({
+  getModelsMetadata: vi.fn(async () => ({ metadata: CATALOG, fromCache: false })),
+}));
+
+const SOURCE = { kind: 'working-tree', scope: 'all' };
+const REPO_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'oc-repo-2607-'));
+
+const setupGitRepo = () => {
+  const run = (args) => {
+    try {
+      return execFileSync('git', args, { cwd: REPO_DIR, encoding: 'utf8' });
+    } catch (error) {
+      throw new Error(`git ${args.join(' ')} failed: ${error.stderr?.toString() ?? error.message}`);
+    }
+  };
+
+  run(['init', '-b', 'main']);
+  run(['config', 'user.email', 'test@example.com']);
+  run(['config', 'user.name', 'Test']);
+  fs.mkdirSync(path.join(REPO_DIR, 'src'), { recursive: true });
+  fs.writeFileSync(path.join(REPO_DIR, 'src', 'a.ts'), 'export const a = 1;\n', 'utf8');
+  run(['add', 'src/a.ts']);
+  run(['commit', '-m', 'init']);
+  fs.writeFileSync(path.join(REPO_DIR, 'src', 'a.ts'), 'export const a = 1;\nexport const b = 2;\n', 'utf8');
+};
+
+let walkthrough;
+let callSmallModel;
+
+describe('issue 2607 — walkthrough blocks unauthenticated providers', () => {
+  beforeAll(async () => {
+    setupGitRepo();
+    fs.writeFileSync(
+      path.join(REPO_DIR, 'opencode.json'),
+      JSON.stringify({ small_model: 'deepseek/deepseek-v4-flash' }, null, 2),
+      'utf8',
+    );
+
+    walkthrough = await import('./index.js');
+    callSmallModel = await import('../small-model/call.js');
+  });
+
+  afterAll(() => {
+    fs.rmSync(TEMP_HOME, { recursive: true, force: true });
+    fs.rmSync(REPO_DIR, { recursive: true, force: true });
+  });
+
+  it('resolves the deepseek model but reports not ready without a login', async () => {
+    const result = await walkthrough.getWalkthrough({ directory: REPO_DIR, source: SOURCE });
+
+    expect(result.readiness.ready).toBe(false);
+    expect(result.readiness.reason).toBe('no-provider-login');
+    expect(result.readiness.model).toMatchObject({
+      providerID: 'deepseek',
+      modelID: 'deepseek-v4-flash',
+      hasLogin: false,
+    });
+  });
+
+  it('callSmallModel throws a structured no-provider-login error', async () => {
+    const error = await callSmallModel.callSmallModel({
+      auth: {},
+      catalog: CATALOG,
+      workingDirectory: REPO_DIR,
+      providerID: 'deepseek',
+      modelID: 'deepseek-v4-flash',
+      prompt: 'x',
+    }).then(() => null, (e) => e);
+
+    expect(error).toBeInstanceOf(Error);
+    expect(error.message).toBe('No OpenCode login found for provider "deepseek"');
+    expect(error.code).toBe('no-provider-login');
+    expect(error.statusCode).toBe(401);
+  });
+
+  it('generateWalkthrough rejects with structured no-provider-login', async () => {
+    const error = await walkthrough.generateWalkthrough({ directory: REPO_DIR, source: SOURCE })
+      .then(() => null, (e) => e);
+
+    expect(error).toBeInstanceOf(Error);
+    expect(error.code).toBe('no-provider-login');
+    expect(error.statusCode).toBe(401);
+    expect(error.model).toMatchObject({ providerID: 'deepseek', modelID: 'deepseek-v4-flash' });
+  });
+
+  it('answers the generate route with HTTP 401 and code no-provider-login', async () => {
+    const service = { ...walkthrough, getPullRequestDiff: async () => { throw new Error('not used'); } };
+    const app = express();
+    app.use(express.json());
+    const { registerWalkthroughRoutes } = await import('./routes.js');
+    registerWalkthroughRoutes(app, { getWalkthroughService: async () => service });
+
+    const server = app.listen(0);
+    await new Promise((resolve) => server.once('listening', resolve));
+    const base = `http://127.0.0.1:${server.address().port}`;
+    try {
+      const response = await fetch(`${base}/api/walkthrough/generate`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ directory: REPO_DIR, source: SOURCE }),
+      });
+      const body = await response.json();
+
+      expect(response.status).toBe(401);
+      expect(body.code).toBe('no-provider-login');
+      expect(body.model).toMatchObject({ providerID: 'deepseek', modelID: 'deepseek-v4-flash' });
+    } finally {
+      await new Promise((resolve) => server.close(resolve));
+    }
+  });
+});

From 35f17e9e96be0ca5ef6a940bf7c95d45859ea57f Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Tue, 4 Aug 2026 12:22:54 +0000
Subject: [PATCH 04/57] fix(walkthrough): hide unauthenticated models and
 disable Generate

Do not present a provider without a login as the selected walkthrough
model, and grey out Generate when readiness is false instead of showing
a login-error blocker or raw auth banner.

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>
---
 .../views/walkthrough/WalkthroughBlocker.tsx  |  9 +---
 .../views/walkthrough/WalkthroughView.tsx     | 46 +++++++++++++++----
 packages/ui/src/lib/i18n/messages/de.ts       |  3 --
 packages/ui/src/lib/i18n/messages/en.ts       |  3 --
 packages/ui/src/lib/i18n/messages/es.ts       |  3 --
 packages/ui/src/lib/i18n/messages/fr.ts       |  3 --
 packages/ui/src/lib/i18n/messages/ja.ts       |  3 --
 packages/ui/src/lib/i18n/messages/ko.ts       |  3 --
 packages/ui/src/lib/i18n/messages/pl.ts       |  3 --
 packages/ui/src/lib/i18n/messages/pt-BR.ts    |  3 --
 packages/ui/src/lib/i18n/messages/uk.ts       |  3 --
 packages/ui/src/lib/i18n/messages/zh-CN.ts    |  3 --
 packages/ui/src/lib/i18n/messages/zh-TW.ts    |  3 --
 packages/ui/src/lib/walkthrough/types.ts      |  2 +
 .../server/lib/walkthrough/DOCUMENTATION.md   |  7 +--
 packages/web/server/lib/walkthrough/index.js  |  5 +-
 .../lib/walkthrough/reproduce-2607.test.js    |  7 +--
 17 files changed, 49 insertions(+), 60 deletions(-)

diff --git a/packages/ui/src/components/views/walkthrough/WalkthroughBlocker.tsx b/packages/ui/src/components/views/walkthrough/WalkthroughBlocker.tsx
index f23696be..2f0af021 100644
--- a/packages/ui/src/components/views/walkthrough/WalkthroughBlocker.tsx
+++ b/packages/ui/src/components/views/walkthrough/WalkthroughBlocker.tsx
@@ -41,8 +41,7 @@ export const WalkthroughBlocker = ({
   // Settings.
   const canChooseModel = reason === 'context-too-small'
     || reason === 'structured-output-unsupported'
-    || reason === 'output-exhausted'
-    || reason === 'no-provider-login';
+    || reason === 'output-exhausted';
 
   useEffect(() => {
     if (!canChooseModel || providers !== undefined) return;
@@ -101,11 +100,6 @@ export const WalkthroughBlocker = ({
 
   const description = () => {
     if (reason === 'no-model') return t('walkthrough.blocked.noModel.description');
-    if (reason === 'no-provider-login') {
-      return label
-        ? t('walkthrough.blocked.noProviderLogin.description', { model: label })
-        : t('walkthrough.blocked.noProviderLogin.descriptionUnknownModel');
-    }
     if (reason === 'empty-diff') return t('walkthrough.blocked.emptyDiff.description');
     if (reason === 'only-generated') return t('walkthrough.blocked.onlyGenerated.description');
     if (reason === 'output-exhausted') {
@@ -129,7 +123,6 @@ export const WalkthroughBlocker = ({
 
   const title = () => {
     if (reason === 'no-model') return t('walkthrough.blocked.noModel.title');
-    if (reason === 'no-provider-login') return t('walkthrough.blocked.noProviderLogin.title');
     if (reason === 'empty-diff') return t('walkthrough.blocked.emptyDiff.title');
     if (reason === 'only-generated') return t('walkthrough.blocked.onlyGenerated.title');
     if (reason === 'output-exhausted') return t('walkthrough.blocked.outputExhausted.title');
diff --git a/packages/ui/src/components/views/walkthrough/WalkthroughView.tsx b/packages/ui/src/components/views/walkthrough/WalkthroughView.tsx
index 15b9baa8..2c53641d 100644
--- a/packages/ui/src/components/views/walkthrough/WalkthroughView.tsx
+++ b/packages/ui/src/components/views/walkthrough/WalkthroughView.tsx
@@ -323,15 +323,34 @@ export const WalkthroughView = ({ directory }: WalkthroughViewProps) => {
   // Explicit pick first, then the model that actually produced what is on
   // screen, then whatever settings resolve to. The middle step is what makes
   // reopening a review show the model behind it rather than the default.
-  const activeModel = selectedModel
-    ?? (entry.result?.model ? `${entry.result.model.providerID}/${entry.result.model.modelID}` : undefined)
-    ?? (entry.readiness?.model ? `${entry.readiness.model.providerID}/${entry.readiness.model.modelID}` : undefined);
-  const [activeProviderId, ...activeModelParts] = (activeModel ?? '').split('/');
-  const activeModelId = activeModelParts.join('/');
-
+  // Never present a provider without a usable login as the current selection —
+  // the picker already hides them from the menu; showing one as selected was
+  // the whole "why say so?" failure mode.
   const modelsMetadata = useConfigStore((state) => state.modelsMetadata);
   const [modelProviders, setModelProviders] = useState<string[] | undefined>(undefined);
 
+  const providerIsAuthenticated = (providerId: string | undefined) => {
+    if (!providerId) return false;
+    if (modelProviders === undefined) return true;
+    return modelProviders.includes(providerId);
+  };
+  const readinessModelRef = entry.readiness?.model
+    && entry.readiness.model.hasLogin !== false
+    && providerIsAuthenticated(entry.readiness.model.providerID)
+    ? `${entry.readiness.model.providerID}/${entry.readiness.model.modelID}`
+    : undefined;
+  const resultModelRef = entry.result?.model
+    && providerIsAuthenticated(entry.result.model.providerID)
+    ? `${entry.result.model.providerID}/${entry.result.model.modelID}`
+    : undefined;
+  const selectedModelUsable = selectedModel
+    && providerIsAuthenticated(selectedModel.split('/')[0])
+    ? selectedModel
+    : undefined;
+  const activeModel = selectedModelUsable ?? resultModelRef ?? readinessModelRef;
+  const [activeProviderId, ...activeModelParts] = (activeModel ?? '').split('/');
+  const activeModelId = activeModelParts.join('/');
+
   useEffect(() => {
     if (modelProviders !== undefined) return;
     let cancelled = false;
@@ -403,15 +422,17 @@ export const WalkthroughView = ({ directory }: WalkthroughViewProps) => {
 
   const showStages = startedFromEmptyRef.current
     && (entry.status === 'generating' || stageProgress.holding);
+  // Auth/login gaps are not a full-panel blocker: hide the unusable model and
+  // disable Generate instead of explaining a raw provider error.
   const blockedReason = entry.error?.code === 'context-too-small'
     || entry.error?.code === 'structured-output-unsupported'
     || entry.error?.code === 'no-model'
-    || entry.error?.code === 'no-provider-login'
     || entry.error?.code === 'empty-diff'
     || entry.error?.code === 'only-generated'
     || entry.error?.code === 'output-exhausted'
     ? entry.error.code
     : entry.readiness && !entry.readiness.ready && !view
+      && entry.readiness.reason !== 'no-provider-login'
       ? entry.readiness.reason
       : undefined;
 
@@ -421,11 +442,16 @@ export const WalkthroughView = ({ directory }: WalkthroughViewProps) => {
   const blockedRequiredChars = entry.error?.requiredChars ?? entry.readiness?.requiredChars;
   const blockedAvailableChars = entry.error?.availableChars ?? entry.readiness?.availableChars;
 
+  // Not ready means Generate must not look actionable — including when the
+  // resolved model has no login (reason no-provider-login).
+  const generateDisabled = Boolean(entry.readiness && !entry.readiness.ready);
+
   const handleGenerate = useCallback(
     (force: boolean) => {
+      if (generateDisabled) return;
       void generate(directory, source, { force, language: activeLanguage });
     },
-    [activeLanguage, directory, generate, source]
+    [activeLanguage, directory, generate, generateDisabled, source]
   );
 
   return (
@@ -594,6 +620,7 @@ export const WalkthroughView = ({ directory }: WalkthroughViewProps) => {
               variant="outline"
               size="sm"
               className={WALKTHROUGH_ACTION_CLASS}
+              disabled={generateDisabled}
               aria-label={compactHeader
                 ? (view ? t('walkthrough.action.regenerate') : t('walkthrough.action.generate'))
                 : undefined}
@@ -647,6 +674,7 @@ export const WalkthroughView = ({ directory }: WalkthroughViewProps) => {
             variant="ghost"
             size="xs"
             className="ml-auto"
+            disabled={generateDisabled}
             // Not forced: if an entry for this exact request existed the banner
             // would not be here, and a forced run would refuse the cache it may
             // find on the way.
@@ -678,7 +706,7 @@ export const WalkthroughView = ({ directory }: WalkthroughViewProps) => {
         </div>
       )}
 
-      {entry.error && !blockedReason && (
+      {entry.error && !blockedReason && entry.error.code !== 'no-provider-login' && (
         <div className="flex shrink-0 items-start gap-2 border-b border-border/60 bg-status-error/10 px-3 py-2">
           <Icon name="error-warning" className="mt-0.5 size-4 shrink-0 text-status-error" />
           {/* Provider errors arrive as raw JSON bodies. Show a readable amount
diff --git a/packages/ui/src/lib/i18n/messages/de.ts b/packages/ui/src/lib/i18n/messages/de.ts
index 4f353026..0db76c86 100644
--- a/packages/ui/src/lib/i18n/messages/de.ts
+++ b/packages/ui/src/lib/i18n/messages/de.ts
@@ -2866,9 +2866,6 @@ export const dict = {
   'walkthrough.importance.context': 'Kontext',
   'walkthrough.blocked.noModel.title': 'Kein Modell ausgewählt',
   'walkthrough.blocked.noModel.description': 'Wählen Sie zuerst ein Modell aus.',
-  'walkthrough.blocked.noProviderLogin.title': 'Dieser Anbieter ist nicht angemeldet',
-  'walkthrough.blocked.noProviderLogin.description': '{model} braucht eine Anmeldung bei seinem Anbieter. Melde dich an oder wähle ein Modell eines Anbieters, den du bereits nutzt.',
-  'walkthrough.blocked.noProviderLogin.descriptionUnknownModel': 'Das ausgewählte Modell braucht eine Anmeldung bei seinem Anbieter. Melde dich an oder wähle ein Modell eines Anbieters, den du bereits nutzt.',
   'walkthrough.blocked.emptyDiff.title': 'Kein Diff vorhanden',
   'walkthrough.blocked.emptyDiff.description': 'Es gibt keine Änderungen, die zusammengefasst werden können.',
   'walkthrough.blocked.contextTooSmall.title': 'Kontext zu klein',
diff --git a/packages/ui/src/lib/i18n/messages/en.ts b/packages/ui/src/lib/i18n/messages/en.ts
index 53929a2f..17d137e5 100644
--- a/packages/ui/src/lib/i18n/messages/en.ts
+++ b/packages/ui/src/lib/i18n/messages/en.ts
@@ -1147,9 +1147,6 @@ export const dict = {
   'walkthrough.importance.context': 'Context',
   'walkthrough.blocked.noModel.title': 'No small model available',
   'walkthrough.blocked.noModel.description': 'Sign in to a model provider to generate a review.',
-  'walkthrough.blocked.noProviderLogin.title': 'This provider is not signed in',
-  'walkthrough.blocked.noProviderLogin.description': '{model} needs a login for its provider. Sign in, or choose a model from a provider you already use.',
-  'walkthrough.blocked.noProviderLogin.descriptionUnknownModel': 'The selected model needs a login for its provider. Sign in, or choose a model from a provider you already use.',
   'walkthrough.blocked.emptyDiff.title': 'Nothing to review',
   'walkthrough.blocked.emptyDiff.description': 'There are no changes in this scope yet.',
   'walkthrough.blocked.contextTooSmall.title': 'This diff is too large for the current model',
diff --git a/packages/ui/src/lib/i18n/messages/es.ts b/packages/ui/src/lib/i18n/messages/es.ts
index 140e686e..ea5086d0 100644
--- a/packages/ui/src/lib/i18n/messages/es.ts
+++ b/packages/ui/src/lib/i18n/messages/es.ts
@@ -1148,9 +1148,6 @@ export const dict: Record<I18nKey, string> = {
   "walkthrough.importance.context": "Contexto",
   "walkthrough.blocked.noModel.title": "No hay ningún modelo pequeño disponible",
   "walkthrough.blocked.noModel.description": "Inicia sesión en un proveedor de modelos para generar una revisión.",
-  "walkthrough.blocked.noProviderLogin.title": "Este proveedor no tiene sesión iniciada",
-  "walkthrough.blocked.noProviderLogin.description": "{model} necesita un inicio de sesión en su proveedor. Inicia sesión o elige un modelo de un proveedor que ya uses.",
-  "walkthrough.blocked.noProviderLogin.descriptionUnknownModel": "El modelo seleccionado necesita un inicio de sesión en su proveedor. Inicia sesión o elige un modelo de un proveedor que ya uses.",
   "walkthrough.blocked.emptyDiff.title": "Nada que revisar",
   "walkthrough.blocked.emptyDiff.description": "Todavía no hay cambios en este ámbito.",
   "walkthrough.blocked.contextTooSmall.title": "Este diff es demasiado grande para el modelo actual",
diff --git a/packages/ui/src/lib/i18n/messages/fr.ts b/packages/ui/src/lib/i18n/messages/fr.ts
index 479033dc..3a625450 100644
--- a/packages/ui/src/lib/i18n/messages/fr.ts
+++ b/packages/ui/src/lib/i18n/messages/fr.ts
@@ -972,9 +972,6 @@ export const dict = {
   'walkthrough.importance.context': 'Contexte',
   'walkthrough.blocked.noModel.title': 'Aucun petit modèle disponible',
   'walkthrough.blocked.noModel.description': 'Connectez-vous à un fournisseur de modèles pour générer une revue.',
-  'walkthrough.blocked.noProviderLogin.title': 'Ce fournisseur n’est pas connecté',
-  'walkthrough.blocked.noProviderLogin.description': '{model} nécessite une connexion à son fournisseur. Connectez-vous, ou choisissez un modèle d’un fournisseur que vous utilisez déjà.',
-  'walkthrough.blocked.noProviderLogin.descriptionUnknownModel': 'Le modèle sélectionné nécessite une connexion à son fournisseur. Connectez-vous, ou choisissez un modèle d’un fournisseur que vous utilisez déjà.',
   'walkthrough.blocked.emptyDiff.title': 'Rien à examiner',
   'walkthrough.blocked.emptyDiff.description': 'Il n’y a encore aucune modification dans cette portée.',
   'walkthrough.blocked.contextTooSmall.title': 'Ce diff est trop volumineux pour le modèle actuel',
diff --git a/packages/ui/src/lib/i18n/messages/ja.ts b/packages/ui/src/lib/i18n/messages/ja.ts
index ed810851..181ec3e9 100644
--- a/packages/ui/src/lib/i18n/messages/ja.ts
+++ b/packages/ui/src/lib/i18n/messages/ja.ts
@@ -1144,9 +1144,6 @@ export const dict: Record<I18nKey, string> = {
   'walkthrough.importance.context': '補足',
   'walkthrough.blocked.noModel.title': '利用できるスモールモデルがありません',
   'walkthrough.blocked.noModel.description': 'レビューを生成するにはモデルプロバイダーにサインインしてください。',
-  'walkthrough.blocked.noProviderLogin.title': 'このプロバイダーにはサインインしていません',
-  'walkthrough.blocked.noProviderLogin.description': '{model} にはプロバイダーへのログインが必要です。サインインするか、すでに使っているプロバイダーのモデルを選んでください。',
-  'walkthrough.blocked.noProviderLogin.descriptionUnknownModel': '選択したモデルにはプロバイダーへのログインが必要です。サインインするか、すでに使っているプロバイダーのモデルを選んでください。',
   'walkthrough.blocked.emptyDiff.title': 'レビュー対象がありません',
   'walkthrough.blocked.emptyDiff.description': 'この範囲にはまだ変更がありません。',
   'walkthrough.blocked.contextTooSmall.title': 'この差分は現在のモデルには大きすぎます',
diff --git a/packages/ui/src/lib/i18n/messages/ko.ts b/packages/ui/src/lib/i18n/messages/ko.ts
index d9d68816..150a56ce 100644
--- a/packages/ui/src/lib/i18n/messages/ko.ts
+++ b/packages/ui/src/lib/i18n/messages/ko.ts
@@ -1148,9 +1148,6 @@ export const dict: Record<I18nKey, string> = {
   'walkthrough.importance.context': '참고',
   'walkthrough.blocked.noModel.title': '사용할 수 있는 스몰 모델이 없습니다',
   'walkthrough.blocked.noModel.description': '리뷰를 생성하려면 모델 제공자에 로그인하세요.',
-  'walkthrough.blocked.noProviderLogin.title': '이 제공자에 로그인되어 있지 않습니다',
-  'walkthrough.blocked.noProviderLogin.description': '{model}을(를) 쓰려면 해당 제공자에 로그인해야 합니다. 로그인하거나, 이미 사용 중인 제공자의 모델을 선택하세요.',
-  'walkthrough.blocked.noProviderLogin.descriptionUnknownModel': '선택한 모델을 쓰려면 해당 제공자에 로그인해야 합니다. 로그인하거나, 이미 사용 중인 제공자의 모델을 선택하세요.',
   'walkthrough.blocked.emptyDiff.title': '리뷰할 내용이 없습니다',
   'walkthrough.blocked.emptyDiff.description': '이 범위에는 아직 변경 사항이 없습니다.',
   'walkthrough.blocked.contextTooSmall.title': '이 diff는 현재 모델에 너무 큽니다',
diff --git a/packages/ui/src/lib/i18n/messages/pl.ts b/packages/ui/src/lib/i18n/messages/pl.ts
index 949b745f..8f93e1f6 100644
--- a/packages/ui/src/lib/i18n/messages/pl.ts
+++ b/packages/ui/src/lib/i18n/messages/pl.ts
@@ -1460,9 +1460,6 @@ export const dict: Record<I18nKey, string> = {
   'walkthrough.importance.context': 'Kontekst',
   'walkthrough.blocked.noModel.title': 'Brak dostępnego małego modelu',
   'walkthrough.blocked.noModel.description': 'Zaloguj się u dostawcy modeli, aby wygenerować przegląd.',
-  'walkthrough.blocked.noProviderLogin.title': 'Ten dostawca nie jest zalogowany',
-  'walkthrough.blocked.noProviderLogin.description': '{model} wymaga logowania u swojego dostawcy. Zaloguj się albo wybierz model u dostawcy, którego już używasz.',
-  'walkthrough.blocked.noProviderLogin.descriptionUnknownModel': 'Wybrany model wymaga logowania u swojego dostawcy. Zaloguj się albo wybierz model u dostawcy, którego już używasz.',
   'walkthrough.blocked.emptyDiff.title': 'Nie ma czego przeglądać',
   'walkthrough.blocked.emptyDiff.description': 'W tym zakresie nie ma jeszcze zmian.',
   'walkthrough.blocked.contextTooSmall.title': 'Te różnice są za duże dla bieżącego modelu',
diff --git a/packages/ui/src/lib/i18n/messages/pt-BR.ts b/packages/ui/src/lib/i18n/messages/pt-BR.ts
index 6c79996a..44fef67a 100644
--- a/packages/ui/src/lib/i18n/messages/pt-BR.ts
+++ b/packages/ui/src/lib/i18n/messages/pt-BR.ts
@@ -1148,9 +1148,6 @@ export const dict: Record<I18nKey, string> = {
   "walkthrough.importance.context": "Contexto",
   "walkthrough.blocked.noModel.title": "Nenhum modelo pequeno disponível",
   "walkthrough.blocked.noModel.description": "Entre em um provedor de modelos para gerar uma revisão.",
-  "walkthrough.blocked.noProviderLogin.title": "Este provedor não está conectado",
-  "walkthrough.blocked.noProviderLogin.description": "{model} precisa de login no provedor. Entre na conta ou escolha um modelo de um provedor que você já usa.",
-  "walkthrough.blocked.noProviderLogin.descriptionUnknownModel": "O modelo selecionado precisa de login no provedor. Entre na conta ou escolha um modelo de um provedor que você já usa.",
   "walkthrough.blocked.emptyDiff.title": "Nada para revisar",
   "walkthrough.blocked.emptyDiff.description": "Ainda não há mudanças neste escopo.",
   "walkthrough.blocked.contextTooSmall.title": "Este diff é grande demais para o modelo atual",
diff --git a/packages/ui/src/lib/i18n/messages/uk.ts b/packages/ui/src/lib/i18n/messages/uk.ts
index 6005df66..c8663cea 100644
--- a/packages/ui/src/lib/i18n/messages/uk.ts
+++ b/packages/ui/src/lib/i18n/messages/uk.ts
@@ -1148,9 +1148,6 @@ export const dict: Record<I18nKey, string> = {
   "walkthrough.importance.context": "Контекст",
   "walkthrough.blocked.noModel.title": "Немає доступної small model",
   "walkthrough.blocked.noModel.description": "Увійдіть до провайдера моделей, щоб створити розбір.",
-  "walkthrough.blocked.noProviderLogin.title": "У цей провайдер не ввійшли",
-  "walkthrough.blocked.noProviderLogin.description": "{model} потребує входу в його провайдер. Увійдіть або виберіть модель у провайдера, яким ви вже користуєтесь.",
-  "walkthrough.blocked.noProviderLogin.descriptionUnknownModel": "Вибрана модель потребує входу в її провайдер. Увійдіть або виберіть модель у провайдера, яким ви вже користуєтесь.",
   "walkthrough.blocked.emptyDiff.title": "Немає що оглядати",
   "walkthrough.blocked.emptyDiff.description": "У цій області поки що немає змін.",
   "walkthrough.blocked.contextTooSmall.title": "Цей diff завеликий для поточної моделі",
diff --git a/packages/ui/src/lib/i18n/messages/zh-CN.ts b/packages/ui/src/lib/i18n/messages/zh-CN.ts
index 551b95cf..76ffac2f 100644
--- a/packages/ui/src/lib/i18n/messages/zh-CN.ts
+++ b/packages/ui/src/lib/i18n/messages/zh-CN.ts
@@ -1148,9 +1148,6 @@ export const dict: Record<I18nKey, string> = {
   'walkthrough.importance.context': '背景',
   'walkthrough.blocked.noModel.title': '没有可用的小模型',
   'walkthrough.blocked.noModel.description': '请登录模型提供方后再生成评审。',
-  'walkthrough.blocked.noProviderLogin.title': '尚未登录此提供方',
-  'walkthrough.blocked.noProviderLogin.description': '{model} 需要登录其提供方。请先登录，或改选你已在使用的提供方中的模型。',
-  'walkthrough.blocked.noProviderLogin.descriptionUnknownModel': '所选模型需要登录其提供方。请先登录，或改选你已在使用的提供方中的模型。',
   'walkthrough.blocked.emptyDiff.title': '没有可评审的内容',
   'walkthrough.blocked.emptyDiff.description': '该范围内暂无改动。',
   'walkthrough.blocked.contextTooSmall.title': '当前模型无法容纳这份差异',
diff --git a/packages/ui/src/lib/i18n/messages/zh-TW.ts b/packages/ui/src/lib/i18n/messages/zh-TW.ts
index 95b0af8b..3538d59c 100644
--- a/packages/ui/src/lib/i18n/messages/zh-TW.ts
+++ b/packages/ui/src/lib/i18n/messages/zh-TW.ts
@@ -1160,9 +1160,6 @@ export const dict: Record<I18nKey, string> = {
   'walkthrough.importance.context': '背景',
   'walkthrough.blocked.noModel.title': '沒有可用的小模型',
   'walkthrough.blocked.noModel.description': '請先登入模型供應商再產生審閱。',
-  'walkthrough.blocked.noProviderLogin.title': '尚未登入此供應商',
-  'walkthrough.blocked.noProviderLogin.description': '{model} 需要登入其供應商。請先登入，或改選你已在使用的供應商中的模型。',
-  'walkthrough.blocked.noProviderLogin.descriptionUnknownModel': '所選模型需要登入其供應商。請先登入，或改選你已在使用的供應商中的模型。',
   'walkthrough.blocked.emptyDiff.title': '沒有可審閱的內容',
   'walkthrough.blocked.emptyDiff.description': '此範圍目前沒有變更。',
   'walkthrough.blocked.contextTooSmall.title': '目前模型無法容納這份差異',
diff --git a/packages/ui/src/lib/walkthrough/types.ts b/packages/ui/src/lib/walkthrough/types.ts
index 40bfd62e..5f8ef80a 100644
--- a/packages/ui/src/lib/walkthrough/types.ts
+++ b/packages/ui/src/lib/walkthrough/types.ts
@@ -105,6 +105,8 @@ export interface WalkthroughReadiness {
     inputCharBudget?: number;
     contextTokens?: number;
     structuredOutput?: boolean | null;
+    /** False when the resolved provider has no usable OpenCode login. */
+    hasLogin?: boolean;
   };
   requiredChars?: number;
   availableChars?: number;
diff --git a/packages/web/server/lib/walkthrough/DOCUMENTATION.md b/packages/web/server/lib/walkthrough/DOCUMENTATION.md
index 63997184..0f23fac5 100644
--- a/packages/web/server/lib/walkthrough/DOCUMENTATION.md
+++ b/packages/web/server/lib/walkthrough/DOCUMENTATION.md
@@ -121,9 +121,10 @@ silently changes the model behind commit messages.
 A settings or `opencode.json` `small_model` override can still name a provider
 with no usable login (neither `auth.json` nor `provider.<id>.options.apiKey`).
 `describeSmallModel` reports that as `hasLogin: false`, readiness refuses with
-`code: 'no-provider-login'`, and generation maps the same code to HTTP 401 —
-so the panel shows a blocker with a model picker instead of looking ready and
-then dumping the raw `No OpenCode login found for provider "…"` string.
+`reason: 'no-provider-login'` and omits the unusable model so the panel cannot
+present it as selected, and generation maps the same code to HTTP 401. The UI
+disables Generate and keeps the picker on authenticated providers only — it does
+not surface a raw auth error or a special login blocker for this case.
 
 ## Output language
 
diff --git a/packages/web/server/lib/walkthrough/index.js b/packages/web/server/lib/walkthrough/index.js
index 057a2c58..f65d3e2f 100644
--- a/packages/web/server/lib/walkthrough/index.js
+++ b/packages/web/server/lib/walkthrough/index.js
@@ -334,9 +334,10 @@ function computeReadiness({ model, digest, files, fileCount, hunkCount, generate
   }
 
   // A resolved override/config model can still have no usable login. Refuse up
-  // front so the panel does not look ready and then dump a raw auth error.
+  // front and omit the model — offering an unauthenticated selection in the
+  // picker is what made the old raw auth error feel like a product bug.
   if (model.hasLogin === false) {
-    return { ready: false, reason: 'no-provider-login', model };
+    return { ready: false, reason: 'no-provider-login' };
   }
 
   // Built with the same language the generation would use: the instruction is
diff --git a/packages/web/server/lib/walkthrough/reproduce-2607.test.js b/packages/web/server/lib/walkthrough/reproduce-2607.test.js
index 7ef6c15c..8cca6e55 100644
--- a/packages/web/server/lib/walkthrough/reproduce-2607.test.js
+++ b/packages/web/server/lib/walkthrough/reproduce-2607.test.js
@@ -90,11 +90,8 @@ describe('issue 2607 — walkthrough blocks unauthenticated providers', () => {
 
     expect(result.readiness.ready).toBe(false);
     expect(result.readiness.reason).toBe('no-provider-login');
-    expect(result.readiness.model).toMatchObject({
-      providerID: 'deepseek',
-      modelID: 'deepseek-v4-flash',
-      hasLogin: false,
-    });
+    // Unusable models must not be offered as the current selection.
+    expect(result.readiness.model).toBeUndefined();
   });
 
   it('callSmallModel throws a structured no-provider-login error', async () => {

From 5c6eee331ea6f8018f8b2b7d14b80c006d599a01 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Tue, 4 Aug 2026 12:35:25 +0000
Subject: [PATCH 05/57] fix(walkthrough): keep unauthenticated models out of
 the picker

Treat an empty allowedProviderIds list as allow-none, disable Generate
when no usable model is selected, and mute the button styling so it
reads as unavailable rather than actionable.

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>
---
 .../model-picker/ModelPickerList.tsx           |  5 ++++-
 .../views/walkthrough/WalkthroughBlocker.tsx   |  2 +-
 .../views/walkthrough/WalkthroughView.tsx      | 18 ++++++++++++------
 3 files changed, 17 insertions(+), 8 deletions(-)

diff --git a/packages/ui/src/components/model-picker/ModelPickerList.tsx b/packages/ui/src/components/model-picker/ModelPickerList.tsx
index f06dc190..99080f9c 100644
--- a/packages/ui/src/components/model-picker/ModelPickerList.tsx
+++ b/packages/ui/src/components/model-picker/ModelPickerList.tsx
@@ -436,7 +436,10 @@ export const ModelPickerList: React.FC<ModelPickerListProps> = ({
   );
 
   const allowedProviderSet = React.useMemo(() => {
-    if (!allowedProviderIds || allowedProviderIds.length === 0) return null;
+    // undefined = no restriction; [] = allow none. Treating empty like
+    // "unrestricted" would resurface providers without a login in pickers that
+    // intentionally pass the authenticated-only list.
+    if (!allowedProviderIds) return null;
     return new Set(allowedProviderIds);
   }, [allowedProviderIds]);
 
diff --git a/packages/ui/src/components/views/walkthrough/WalkthroughBlocker.tsx b/packages/ui/src/components/views/walkthrough/WalkthroughBlocker.tsx
index 2f0af021..a9a620ac 100644
--- a/packages/ui/src/components/views/walkthrough/WalkthroughBlocker.tsx
+++ b/packages/ui/src/components/views/walkthrough/WalkthroughBlocker.tsx
@@ -150,7 +150,7 @@ export const WalkthroughBlocker = ({
             onChange={(providerId, modelId) => {
               void handleModelChange(providerId, modelId);
             }}
-            allowedProviderIds={providers}
+            allowedProviderIds={providers ?? []}
             isModelAllowed={isStructuredOutputCapable}
           />
         </div>
diff --git a/packages/ui/src/components/views/walkthrough/WalkthroughView.tsx b/packages/ui/src/components/views/walkthrough/WalkthroughView.tsx
index 2c53641d..25a19097 100644
--- a/packages/ui/src/components/views/walkthrough/WalkthroughView.tsx
+++ b/packages/ui/src/components/views/walkthrough/WalkthroughView.tsx
@@ -331,7 +331,9 @@ export const WalkthroughView = ({ directory }: WalkthroughViewProps) => {
 
   const providerIsAuthenticated = (providerId: string | undefined) => {
     if (!providerId) return false;
-    if (modelProviders === undefined) return true;
+    // Until the auth list loads, do not present a candidate as selected —
+    // otherwise an unauthenticated config model flashes in the picker.
+    if (modelProviders === undefined) return false;
     return modelProviders.includes(providerId);
   };
   const readinessModelRef = entry.readiness?.model
@@ -442,9 +444,9 @@ export const WalkthroughView = ({ directory }: WalkthroughViewProps) => {
   const blockedRequiredChars = entry.error?.requiredChars ?? entry.readiness?.requiredChars;
   const blockedAvailableChars = entry.error?.availableChars ?? entry.readiness?.availableChars;
 
-  // Not ready means Generate must not look actionable — including when the
-  // resolved model has no login (reason no-provider-login).
-  const generateDisabled = Boolean(entry.readiness && !entry.readiness.ready);
+  // Not ready, or no usable selected model, means Generate must not look
+  // actionable — including when the resolved model has no login.
+  const generateDisabled = !activeModel || Boolean(entry.readiness && !entry.readiness.ready);
 
   const handleGenerate = useCallback(
     (force: boolean) => {
@@ -571,7 +573,8 @@ export const WalkthroughView = ({ directory }: WalkthroughViewProps) => {
             onChange={(providerId, modelId) => {
               selectModel(directory, source, providerId && modelId ? `${providerId}/${modelId}` : null);
             }}
-            allowedProviderIds={modelProviders}
+            // While the auth list is loading, allow none — not every provider.
+            allowedProviderIds={modelProviders ?? []}
             isModelAllowed={isStructuredOutputCapable}
             tooltipsEnabled={false}
             dropdownPortalToBody
@@ -619,7 +622,10 @@ export const WalkthroughView = ({ directory }: WalkthroughViewProps) => {
               type="button"
               variant="outline"
               size="sm"
-              className={WALKTHROUGH_ACTION_CLASS}
+              className={cn(
+                WALKTHROUGH_ACTION_CLASS,
+                generateDisabled && 'border-border bg-transparent text-muted-foreground hover:bg-transparent hover:text-muted-foreground',
+              )}
               disabled={generateDisabled}
               aria-label={compactHeader
                 ? (view ? t('walkthrough.action.regenerate') : t('walkthrough.action.generate'))

From bc24b8a8366f2c7ab1d84b36177fba48f47a075a Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Tue, 4 Aug 2026 12:43:31 +0000
Subject: [PATCH 06/57] fix(walkthrough): drop info tint from disabled Generate
 button

The status-info classes were winning over muted disabled styles, so the
button still looked actionable when no model was selected.

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>
---
 .../src/components/views/walkthrough/WalkthroughView.tsx   | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/packages/ui/src/components/views/walkthrough/WalkthroughView.tsx b/packages/ui/src/components/views/walkthrough/WalkthroughView.tsx
index 25a19097..246a818c 100644
--- a/packages/ui/src/components/views/walkthrough/WalkthroughView.tsx
+++ b/packages/ui/src/components/views/walkthrough/WalkthroughView.tsx
@@ -622,10 +622,9 @@ export const WalkthroughView = ({ directory }: WalkthroughViewProps) => {
               type="button"
               variant="outline"
               size="sm"
-              className={cn(
-                WALKTHROUGH_ACTION_CLASS,
-                generateDisabled && 'border-border bg-transparent text-muted-foreground hover:bg-transparent hover:text-muted-foreground',
-              )}
+              className={generateDisabled
+                ? 'border-border text-muted-foreground'
+                : WALKTHROUGH_ACTION_CLASS}
               disabled={generateDisabled}
               aria-label={compactHeader
                 ? (view ? t('walkthrough.action.regenerate') : t('walkthrough.action.generate'))

From 65a1eec782f0d496fa026038499133e964566ca3 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Tue, 4 Aug 2026 12:46:48 +0000
Subject: [PATCH 07/57] fix(ui): keep manual model override after delegated
 subtask completes

Synthetic subagent-completion nudges were treated as the latest user model
choice and rehydrated the agent default, while setAgent preferred the agent
pin over the session override. Skip synthetic prompts for restore, preserve
manual selection-store overrides, and prefer session agent models in setAgent.

Closes openchamber/openchamber#2404

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>
---
 .../ui/src/components/chat/ModelControls.tsx  |  63 +++---
 .../src/lib/messages/userModelChoice.test.ts  | 145 +++++++++++++
 .../ui/src/lib/messages/userModelChoice.ts    | 103 +++++++++
 packages/ui/src/stores/useConfigStore.test.ts |  67 ++++++
 packages/ui/src/stores/useConfigStore.ts      |  30 +--
 .../ui/src/sync/__tests__/issue-2404.test.ts  | 200 ++++++++++++++++++
 packages/ui/src/sync/session-ui-store.ts      |  39 ++--
 7 files changed, 579 insertions(+), 68 deletions(-)
 create mode 100644 packages/ui/src/lib/messages/userModelChoice.test.ts
 create mode 100644 packages/ui/src/lib/messages/userModelChoice.ts
 create mode 100644 packages/ui/src/sync/__tests__/issue-2404.test.ts

diff --git a/packages/ui/src/components/chat/ModelControls.tsx b/packages/ui/src/components/chat/ModelControls.tsx
index 3fbf959b..262664b9 100644
--- a/packages/ui/src/components/chat/ModelControls.tsx
+++ b/packages/ui/src/components/chat/ModelControls.tsx
@@ -40,6 +40,11 @@ import { getCurrentIntlLocale, useI18n } from '@/lib/i18n';
 import { useOpenCodeReadiness } from '@/hooks/useOpenCodeReadiness';
 import { eventMatchesShortcut, getEffectiveShortcutCombo, normalizeCombo } from '@/lib/shortcuts';
 import { markStartupTrace } from '@/lib/startupTrace';
+import {
+    findLatestUserModelChoice,
+    shouldPreserveManualModelOverride,
+} from '@/lib/messages/userModelChoice';
+import { getSyncParts } from '@/sync/sync-refs';
 
 type IconComponent = IconName;
 
@@ -645,37 +650,14 @@ export const ModelControls: React.FC<ModelControlsProps> = ({
         currentSessionDirectory ?? undefined,
     );
     const currentSessionMessagesFromSync = useSessionMessages(currentSessionId ?? '', currentSessionDirectory ?? undefined);
+    // Skip synthetic subagent-completion nudges — restoring from them resets a
+    // manual model override back to the agent default (issue #2404).
     const latestLoadedUserChoice = React.useMemo(() => {
-        for (let i = currentSessionMessagesFromSync.length - 1; i >= 0; i -= 1) {
-            const message = currentSessionMessagesFromSync[i] as typeof currentSessionMessagesFromSync[number] & {
-                model?: { providerID?: string; modelID?: string; variant?: string };
-                variant?: string;
-                mode?: string;
-            };
-            if (message.role !== 'user') {
-                continue;
-            }
-
-            const providerID = typeof message.model?.providerID === 'string' && message.model.providerID.trim().length > 0
-                ? message.model.providerID
-                : undefined;
-            const modelID = typeof message.model?.modelID === 'string' && message.model.modelID.trim().length > 0
-                ? message.model.modelID
-                : undefined;
-            const agent = typeof message.agent === 'string' && message.agent.trim().length > 0
-                ? message.agent
-                : (typeof message.mode === 'string' && message.mode.trim().length > 0 ? message.mode : undefined);
-            // OpenCode 1.4.0 moved variant from top-level to model.variant.
-            // Prefer the new location, fall back to the legacy one for older servers.
-            const variantCandidate = message.model?.variant ?? message.variant;
-            const variant = typeof variantCandidate === 'string' && variantCandidate.trim().length > 0
-                ? variantCandidate
-                : undefined;
-
-            return { id: message.id, agent, providerID, modelID, variant };
-        }
-        return null;
-    }, [currentSessionMessagesFromSync]);
+        return findLatestUserModelChoice(
+            currentSessionMessagesFromSync,
+            (messageId) => getSyncParts(messageId, currentSessionDirectory ?? undefined),
+        );
+    }, [currentSessionDirectory, currentSessionMessagesFromSync]);
 
     const tryApplyModelSelection = React.useCallback(
         (providerId: string, modelId: string, agentName?: string): ModelApplyResult => {
@@ -828,6 +810,25 @@ export const ModelControls: React.FC<ModelControlsProps> = ({
             return;
         }
 
+        // Manual session override wins over historical / synthetic message metadata.
+        const savedSessionModel = getSessionModelSelection(currentSessionId);
+        if (shouldPreserveManualModelOverride({
+            selectionSource: useConfigStore.getState().selectionSource,
+            savedSessionModel,
+            candidate: latestLoadedUserChoice,
+        })) {
+            if (savedSessionModel) {
+                applyModelSelectionWithVariant(
+                    savedSessionModel.providerId,
+                    savedSessionModel.modelId,
+                    resolveModelVariantSelection(savedSessionModel.providerId, savedSessionModel.modelId),
+                    currentAgentName || undefined,
+                );
+            }
+            latestLoadedUserChoiceRestoreRef.current = restoreKey;
+            return;
+        }
+
         if (latestLoadedUserChoice.agent && currentAgentName !== latestLoadedUserChoice.agent) {
             setAgent(latestLoadedUserChoice.agent);
         }
@@ -869,6 +870,8 @@ export const ModelControls: React.FC<ModelControlsProps> = ({
         setAgent,
         applyModelSelectionWithVariant,
         getModelVariantOptions,
+        getSessionModelSelection,
+        resolveModelVariantSelection,
         saveSessionAgentSelection,
         saveAgentModelVariantForSession,
         saveSessionModelSelection,
diff --git a/packages/ui/src/lib/messages/userModelChoice.test.ts b/packages/ui/src/lib/messages/userModelChoice.test.ts
new file mode 100644
index 00000000..e0c43ef9
--- /dev/null
+++ b/packages/ui/src/lib/messages/userModelChoice.test.ts
@@ -0,0 +1,145 @@
+import { describe, expect, test } from 'bun:test'
+import type { Message, Part } from '@opencode-ai/sdk/v2'
+
+import {
+  extractUserModelChoice,
+  findLatestUserModelChoice,
+  shouldPreserveManualModelOverride,
+} from './userModelChoice'
+
+const userMessage = (
+  id: string,
+  model: { providerID: string; modelID: string },
+  agent = 'custom-agent',
+): Message => ({
+  id,
+  sessionID: 'ses_1',
+  role: 'user',
+  time: { created: 1 },
+  agent,
+  model,
+} as Message)
+
+const assistantMessage = (id: string): Message => ({
+  id,
+  sessionID: 'ses_1',
+  role: 'assistant',
+  time: { created: 2 },
+  parentID: 'u1',
+  modelID: 'model-a',
+  providerID: 'provider',
+} as Message)
+
+const textPart = (id: string, text: string, synthetic = false): Part => ({
+  id,
+  sessionID: 'ses_1',
+  messageID: 'u1',
+  type: 'text',
+  text,
+  ...(synthetic ? { synthetic: true } : {}),
+} as Part)
+
+describe('findLatestUserModelChoice', () => {
+  test('returns the latest real user prompt model', () => {
+    const messages = [
+      userMessage('u1', { providerID: 'provider', modelID: 'model-a' }),
+      assistantMessage('a1'),
+      userMessage('u2', { providerID: 'provider', modelID: 'model-b' }),
+    ]
+    const partsById: Record<string, Part[]> = {
+      u1: [textPart('p1', 'first')],
+      u2: [textPart('p2', 'second')],
+    }
+
+    const choice = findLatestUserModelChoice(messages, (id) => partsById[id])
+    expect(choice?.id).toBe('u2')
+    expect(choice?.modelID).toBe('model-b')
+    expect(choice?.providerID).toBe('provider')
+    expect(choice?.agent).toBe('custom-agent')
+  })
+
+  test('[issue-2404] skips synthetic subagent-completion nudges so manual override is not clobbered', () => {
+    // Real prompt sent with the manual override (model-b).
+    const realPrompt = userMessage('u-real', { providerID: 'provider', modelID: 'model-b' })
+    // After a delegated child session goes idle, OpenCode injects a synthetic
+    // user nudge that often carries the agent default model (model-a).
+    const syntheticNudge = userMessage('u-nudge', { providerID: 'provider', modelID: 'model-a' })
+    const messages = [realPrompt, assistantMessage('a1'), syntheticNudge]
+    const partsById: Record<string, Part[]> = {
+      'u-real': [textPart('p-real', 'please investigate', false)],
+      'u-nudge': [textPart('p-nudge', 'Subagent finished.', true)],
+    }
+
+    const choice = findLatestUserModelChoice(messages, (id) => partsById[id])
+    expect(choice?.id).toBe('u-real')
+    expect(choice?.modelID).toBe('model-b')
+  })
+
+  test('skips user messages whose parts have not loaded yet', () => {
+    const messages = [
+      userMessage('u1', { providerID: 'provider', modelID: 'model-a' }),
+      userMessage('u2', { providerID: 'provider', modelID: 'model-b' }),
+    ]
+    const partsById: Record<string, Part[]> = {
+      u1: [textPart('p1', 'first')],
+      // u2 parts missing
+    }
+
+    const choice = findLatestUserModelChoice(messages, (id) => partsById[id])
+    expect(choice?.id).toBe('u1')
+    expect(choice?.modelID).toBe('model-a')
+  })
+
+  test('returns null when only synthetic user messages exist', () => {
+    const messages = [userMessage('u-nudge', { providerID: 'provider', modelID: 'model-a' })]
+    const partsById: Record<string, Part[]> = {
+      'u-nudge': [textPart('p-nudge', 'Subagent finished.', true)],
+    }
+
+    expect(findLatestUserModelChoice(messages, (id) => partsById[id])).toBeNull()
+  })
+})
+
+describe('shouldPreserveManualModelOverride', () => {
+  test('preserves manual override when it differs from the candidate message model', () => {
+    expect(shouldPreserveManualModelOverride({
+      selectionSource: 'manual',
+      savedSessionModel: { providerId: 'provider', modelId: 'model-b' },
+      candidate: { providerID: 'provider', modelID: 'model-a' },
+    })).toBe(true)
+  })
+
+  test('does not preserve when selection matches the candidate', () => {
+    expect(shouldPreserveManualModelOverride({
+      selectionSource: 'manual',
+      savedSessionModel: { providerId: 'provider', modelId: 'model-b' },
+      candidate: { providerID: 'provider', modelID: 'model-b' },
+    })).toBe(false)
+  })
+
+  test('does not preserve auto selections', () => {
+    expect(shouldPreserveManualModelOverride({
+      selectionSource: 'auto',
+      savedSessionModel: { providerId: 'provider', modelId: 'model-b' },
+      candidate: { providerID: 'provider', modelID: 'model-a' },
+    })).toBe(false)
+  })
+
+  test('preserves manual override when candidate has no model', () => {
+    expect(shouldPreserveManualModelOverride({
+      selectionSource: 'manual',
+      savedSessionModel: { providerId: 'provider', modelId: 'model-b' },
+      candidate: { providerID: undefined, modelID: undefined },
+    })).toBe(true)
+  })
+})
+
+describe('extractUserModelChoice', () => {
+  test('reads variant from model.variant', () => {
+    const message = {
+      ...userMessage('u1', { providerID: 'provider', modelID: 'model-b' }),
+      model: { providerID: 'provider', modelID: 'model-b', variant: 'high' },
+    } as Message
+    expect(extractUserModelChoice(message as never)?.variant).toBe('high')
+  })
+})
diff --git a/packages/ui/src/lib/messages/userModelChoice.ts b/packages/ui/src/lib/messages/userModelChoice.ts
new file mode 100644
index 00000000..a94bfbfc
--- /dev/null
+++ b/packages/ui/src/lib/messages/userModelChoice.ts
@@ -0,0 +1,103 @@
+import type { Message, Part } from '@opencode-ai/sdk/v2'
+
+import { isFullySyntheticMessage } from './synthetic'
+
+type UserModelChoice = {
+  id: string
+  agent?: string
+  providerID?: string
+  modelID?: string
+  variant?: string
+}
+
+type MessageLike = Message & {
+  model?: { providerID?: string; modelID?: string; variant?: string }
+  variant?: string
+  mode?: string
+}
+
+/**
+ * Extract agent/model selection metadata from a user message, if present.
+ */
+export const extractUserModelChoice = (message: MessageLike): UserModelChoice | null => {
+  if (message.role !== 'user') {
+    return null
+  }
+
+  const providerID = typeof message.model?.providerID === 'string' && message.model.providerID.trim().length > 0
+    ? message.model.providerID
+    : undefined
+  const modelID = typeof message.model?.modelID === 'string' && message.model.modelID.trim().length > 0
+    ? message.model.modelID
+    : undefined
+  const agent = typeof message.agent === 'string' && message.agent.trim().length > 0
+    ? message.agent
+    : (typeof message.mode === 'string' && message.mode.trim().length > 0 ? message.mode : undefined)
+  // OpenCode 1.4.0 moved variant from top-level to model.variant.
+  const variantCandidate = message.model?.variant ?? message.variant
+  const variant = typeof variantCandidate === 'string' && variantCandidate.trim().length > 0
+    ? variantCandidate
+    : undefined
+
+  return { id: message.id, agent, providerID, modelID, variant }
+}
+
+/**
+ * Find the latest *real* user prompt's model/agent choice.
+ *
+ * Synthetic user messages (e.g. subagent-completion nudges injected when a
+ * delegated child session goes idle) must not drive the composer model
+ * selector — restoring from them clobber a manual session override and reset
+ * to the agent default.
+ *
+ * Messages whose parts have not been loaded yet are skipped so an incomplete
+ * snapshot cannot be treated as authoritative.
+ */
+export const findLatestUserModelChoice = (
+  messages: readonly MessageLike[],
+  getParts: (messageId: string) => Part[] | undefined,
+): UserModelChoice | null => {
+  for (let i = messages.length - 1; i >= 0; i -= 1) {
+    const message = messages[i]
+    if (message.role !== 'user') {
+      continue
+    }
+
+    const parts = getParts(message.id)
+    if (!Array.isArray(parts) || parts.length === 0) {
+      continue
+    }
+    if (isFullySyntheticMessage(parts)) {
+      continue
+    }
+
+    return extractUserModelChoice(message)
+  }
+
+  return null
+}
+
+/**
+ * When the user has a manual session model override, historical (or synthetic)
+ * user-message metadata must not overwrite it. After a real send the selection
+ * store is updated to match the message, so a conflict means the picker was
+ * changed after the last prompt — keep the override.
+ */
+export const shouldPreserveManualModelOverride = ({
+  selectionSource,
+  savedSessionModel,
+  candidate,
+}: {
+  selectionSource: 'auto' | 'manual' | undefined
+  savedSessionModel: { providerId: string; modelId: string } | null | undefined
+  candidate: Pick<UserModelChoice, 'providerID' | 'modelID'> | null | undefined
+}): boolean => {
+  if (selectionSource !== 'manual' || !savedSessionModel?.providerId || !savedSessionModel.modelId) {
+    return false
+  }
+  if (!candidate?.providerID || !candidate.modelID) {
+    return true
+  }
+  return savedSessionModel.providerId !== candidate.providerID
+    || savedSessionModel.modelId !== candidate.modelID
+}
diff --git a/packages/ui/src/stores/useConfigStore.test.ts b/packages/ui/src/stores/useConfigStore.test.ts
index 0b2b18c6..52dbe3e6 100644
--- a/packages/ui/src/stores/useConfigStore.test.ts
+++ b/packages/ui/src/stores/useConfigStore.test.ts
@@ -522,6 +522,73 @@ describe('useConfigStore provider persistence', () => {
     expect(state.currentVariant).toBe('high');
   });
 
+  test('[issue-2404] setAgent keeps session model override over agent default model', () => {
+    // Custom agent default is model-a; user manually overrode to model-b for this session.
+    // Re-applying setAgent (e.g. after delegated subtask completion rematerializes the
+    // parent) must keep model-b rather than resetting to the agent pin.
+    const sessionId = 'ses_2404_model_override';
+    const multiModelProvider = {
+      ...provider('provider', 'model-a'),
+      models: [
+        provider('provider', 'model-a').models[0],
+        provider('provider', 'model-b').models[0],
+      ],
+    };
+    useSessionUIStore.setState({ currentSessionId: sessionId });
+    useSelectionStore.getState().saveSessionModelSelection(sessionId, 'provider', 'model-b');
+    useSelectionStore.getState().saveAgentModelForSession(sessionId, 'custom-agent', 'provider', 'model-b');
+    useConfigStore.setState({
+      activeDirectoryKey: DIRECTORY,
+      providers: [multiModelProvider],
+      agents: [testAgent('custom-agent', { model: { providerID: 'provider', modelID: 'model-a' } })],
+      currentProviderId: 'provider',
+      currentModelId: 'model-b',
+      currentAgentName: 'custom-agent',
+      selectionSource: 'manual',
+      currentVariant: undefined,
+      directoryScoped: {},
+    });
+
+    useConfigStore.getState().setAgent('custom-agent');
+
+    const state = useConfigStore.getState();
+    expect(state.currentProviderId).toBe('provider');
+    expect(state.currentModelId).toBe('model-b');
+    expect(useSelectionStore.getState().getAgentModelForSession(sessionId, 'custom-agent')).toEqual({
+      providerId: 'provider',
+      modelId: 'model-b',
+    });
+  });
+
+  test('[issue-2404] setAgent uses agent default when no session override exists', () => {
+    const sessionId = 'ses_2404_agent_default';
+    const multiModelProvider = {
+      ...provider('provider', 'model-a'),
+      models: [
+        provider('provider', 'model-a').models[0],
+        provider('provider', 'model-b').models[0],
+      ],
+    };
+    useSessionUIStore.setState({ currentSessionId: sessionId });
+    useConfigStore.setState({
+      activeDirectoryKey: DIRECTORY,
+      providers: [multiModelProvider],
+      agents: [testAgent('custom-agent', { model: { providerID: 'provider', modelID: 'model-a' } })],
+      currentProviderId: 'provider',
+      currentModelId: 'model-b',
+      currentAgentName: undefined,
+      selectionSource: 'auto',
+      currentVariant: undefined,
+      directoryScoped: {},
+    });
+
+    useConfigStore.getState().setAgent('custom-agent');
+
+    const state = useConfigStore.getState();
+    expect(state.currentProviderId).toBe('provider');
+    expect(state.currentModelId).toBe('model-a');
+  });
+
   test('loadAgents does not fetch OpenCode config directly', async () => {
     useConfigStore.setState({
       activeDirectoryKey: DIRECTORY,
diff --git a/packages/ui/src/stores/useConfigStore.ts b/packages/ui/src/stores/useConfigStore.ts
index 4fe82ee2..4a7dfd2e 100644
--- a/packages/ui/src/stores/useConfigStore.ts
+++ b/packages/ui/src/stores/useConfigStore.ts
@@ -2503,20 +2503,13 @@ export const useConfigStore = create<ConfigStore>()(
                             return undefined;
                         };
 
-                        // Prefer the selected agent's configured model when switching agents.
                         const agent = agents.find((candidate) => candidate.name === agentName);
-                        const agentModelSelection = agent?.model;
-                        if (agentModelSelection?.providerID && agentModelSelection?.modelID) {
-                            const { providerID, modelID } = agentModelSelection;
-                            const agentProvider = providers.find((provider) => provider.id === providerID);
-                            const agentModel = agentProvider?.models.find((model) => model.id === modelID);
-
-                            if (agentModel) {
-                                applyResolvedModelSelection(providerID, modelID, resolveVariantForModel(providerID, modelID, agent?.variant));
-                                return;
-                            }
-                        }
 
+                        // Prefer a session-level manual override for this agent over the
+                        // agent's configured default. Re-applying setAgent after subtask
+                        // completion / rematerialization must not clobber the override
+                        // (issue #2404). Explicit agent-picker switches still force the
+                        // agent default via ModelControls' shouldPreferAgentModel path.
                         if (currentSessionId) {
                             const existingAgentModel = useSelectionStore.getState().getAgentModelForSession(currentSessionId, agentName);
                             if (existingAgentModel && hasProviderModel(providers, existingAgentModel.providerId, existingAgentModel.modelId)) {
@@ -2532,6 +2525,19 @@ export const useConfigStore = create<ConfigStore>()(
                             }
                         }
 
+                        // No session override — use the agent's configured/pinned model.
+                        const agentModelSelection = agent?.model;
+                        if (agentModelSelection?.providerID && agentModelSelection?.modelID) {
+                            const { providerID, modelID } = agentModelSelection;
+                            const agentProvider = providers.find((provider) => provider.id === providerID);
+                            const agentModel = agentProvider?.models.find((model) => model.id === modelID);
+
+                            if (agentModel) {
+                                applyResolvedModelSelection(providerID, modelID, resolveVariantForModel(providerID, modelID, agent?.variant));
+                                return;
+                            }
+                        }
+
                         // If the agent has no preferred model, use settings default.
                         if (settingsDefaultModel) {
                             const parsed = parseModelString(settingsDefaultModel);
diff --git a/packages/ui/src/sync/__tests__/issue-2404.test.ts b/packages/ui/src/sync/__tests__/issue-2404.test.ts
new file mode 100644
index 00000000..16bf87a5
--- /dev/null
+++ b/packages/ui/src/sync/__tests__/issue-2404.test.ts
@@ -0,0 +1,200 @@
+import { beforeEach, describe, expect, test } from 'bun:test'
+import type { Message, Part } from '@opencode-ai/sdk/v2'
+
+import {
+  findLatestUserModelChoice,
+  shouldPreserveManualModelOverride,
+} from '@/lib/messages/userModelChoice'
+
+/**
+ * Regression for openchamber/openchamber#2404:
+ * custom agent default model A → manual override to B → delegate subtask →
+ * after child completes, synthetic completion nudge must not revert to A.
+ */
+describe('issue #2404 model override persistence across delegated subtask', () => {
+  const sessionId = 'ses_2404'
+  const agentName = 'custom-agent'
+  const agentDefault = { providerID: 'provider', modelID: 'model-a' }
+  const manualOverride = { providerID: 'provider', modelID: 'model-b' }
+
+  let sessionModelSelections: Map<string, { providerId: string; modelId: string }>
+  let sessionAgentModelSelections: Map<string, Map<string, { providerId: string; modelId: string }>>
+  let selectionSource: 'auto' | 'manual'
+  let currentProviderId: string
+  let currentModelId: string
+
+  beforeEach(() => {
+    sessionModelSelections = new Map()
+    sessionAgentModelSelections = new Map()
+    selectionSource = 'auto'
+    currentProviderId = agentDefault.providerID
+    currentModelId = agentDefault.modelID
+  })
+
+  const createSessionWithAgentDefault = () => {
+    // Session starts on the custom agent's pinned model A.
+    currentProviderId = agentDefault.providerID
+    currentModelId = agentDefault.modelID
+    selectionSource = 'auto'
+    sessionModelSelections.set(sessionId, {
+      providerId: agentDefault.providerID,
+      modelId: agentDefault.modelID,
+    })
+    sessionAgentModelSelections.set(sessionId, new Map([
+      [agentName, { providerId: agentDefault.providerID, modelId: agentDefault.modelID }],
+    ]))
+  }
+
+  const setManualModelOverride = () => {
+    selectionSource = 'manual'
+    currentProviderId = manualOverride.providerID
+    currentModelId = manualOverride.modelID
+    sessionModelSelections.set(sessionId, {
+      providerId: manualOverride.providerID,
+      modelId: manualOverride.modelID,
+    })
+    const agentMap = sessionAgentModelSelections.get(sessionId) ?? new Map()
+    agentMap.set(agentName, {
+      providerId: manualOverride.providerID,
+      modelId: manualOverride.modelID,
+    })
+    sessionAgentModelSelections.set(sessionId, agentMap)
+  }
+
+  const completeDelegatedSubtask = () => {
+    // Parent already has the real user prompt (sent with override B) plus a
+    // synthetic subagent-completion nudge that carries the agent default A.
+    const messages: Message[] = [
+      {
+        id: 'u-real',
+        sessionID: sessionId,
+        role: 'user',
+        time: { created: 1 },
+        agent: agentName,
+        model: manualOverride,
+      } as Message,
+      {
+        id: 'a1',
+        sessionID: sessionId,
+        role: 'assistant',
+        time: { created: 2 },
+        parentID: 'u-real',
+        providerID: manualOverride.providerID,
+        modelID: manualOverride.modelID,
+      } as Message,
+      {
+        id: 'u-nudge',
+        sessionID: sessionId,
+        role: 'user',
+        time: { created: 3 },
+        agent: agentName,
+        model: agentDefault,
+      } as Message,
+    ]
+    const partsById: Record<string, Part[]> = {
+      'u-real': [{
+        id: 'p-real',
+        sessionID: sessionId,
+        messageID: 'u-real',
+        type: 'text',
+        text: 'Delegate a subtask',
+      } as Part],
+      'u-nudge': [{
+        id: 'p-nudge',
+        sessionID: sessionId,
+        messageID: 'u-nudge',
+        type: 'text',
+        text: 'Subagent finished.',
+        synthetic: true,
+      } as Part],
+    }
+
+    const latestChoice = findLatestUserModelChoice(messages, (id) => partsById[id])
+    const saved = sessionModelSelections.get(sessionId) ?? null
+
+    // Composer restore must ignore the synthetic nudge and keep the override.
+    expect(latestChoice?.modelID).toBe(manualOverride.modelID)
+    expect(shouldPreserveManualModelOverride({
+      selectionSource,
+      savedSessionModel: saved,
+      candidate: {
+        providerID: agentDefault.providerID,
+        modelID: agentDefault.modelID,
+      },
+    })).toBe(true)
+
+    // Re-applying the session agent (as ModelControls may after rematerialization)
+    // must also prefer the stored override over the agent pin.
+    const agentOverride = sessionAgentModelSelections.get(sessionId)?.get(agentName)
+    if (agentOverride) {
+      currentProviderId = agentOverride.providerId
+      currentModelId = agentOverride.modelId
+    } else {
+      currentProviderId = agentDefault.providerID
+      currentModelId = agentDefault.modelID
+    }
+  }
+
+  test('manual override survives delegated subtask completion', () => {
+    createSessionWithAgentDefault()
+    setManualModelOverride()
+    completeDelegatedSubtask()
+
+    expect(selectionSource).toBe('manual')
+    expect(currentProviderId).toBe(manualOverride.providerID)
+    expect(currentModelId).toBe(manualOverride.modelID)
+    expect(sessionModelSelections.get(sessionId)).toEqual({
+      providerId: manualOverride.providerID,
+      modelId: manualOverride.modelID,
+    })
+  })
+
+  test('agent default is used when no manual override was set', () => {
+    createSessionWithAgentDefault()
+    // No setManualModelOverride — stay on agent default through subtask completion.
+    const messages: Message[] = [
+      {
+        id: 'u-real',
+        sessionID: sessionId,
+        role: 'user',
+        time: { created: 1 },
+        agent: agentName,
+        model: agentDefault,
+      } as Message,
+      {
+        id: 'u-nudge',
+        sessionID: sessionId,
+        role: 'user',
+        time: { created: 2 },
+        agent: agentName,
+        model: agentDefault,
+      } as Message,
+    ]
+    const partsById: Record<string, Part[]> = {
+      'u-real': [{
+        id: 'p-real',
+        sessionID: sessionId,
+        messageID: 'u-real',
+        type: 'text',
+        text: 'Delegate a subtask',
+      } as Part],
+      'u-nudge': [{
+        id: 'p-nudge',
+        sessionID: sessionId,
+        messageID: 'u-nudge',
+        type: 'text',
+        text: 'Subagent finished.',
+        synthetic: true,
+      } as Part],
+    }
+
+    const latestChoice = findLatestUserModelChoice(messages, (id) => partsById[id])
+    expect(latestChoice?.modelID).toBe(agentDefault.modelID)
+    expect(shouldPreserveManualModelOverride({
+      selectionSource: 'auto',
+      savedSessionModel: sessionModelSelections.get(sessionId),
+      candidate: latestChoice,
+    })).toBe(false)
+    expect(currentModelId).toBe(agentDefault.modelID)
+  })
+})
diff --git a/packages/ui/src/sync/session-ui-store.ts b/packages/ui/src/sync/session-ui-store.ts
index 895f5062..4ecdb87d 100644
--- a/packages/ui/src/sync/session-ui-store.ts
+++ b/packages/ui/src/sync/session-ui-store.ts
@@ -30,6 +30,7 @@ import { markPendingUserSendAnimation } from "@/lib/userSendAnimation"
 import { normalizePath } from "@/lib/pathNormalization"
 import { flattenAssistantTextParts } from "@/lib/messages/messageText"
 import { composeForkSessionMessage } from "@/lib/messages/executionMeta"
+import { findLatestUserModelChoice } from "@/lib/messages/userModelChoice"
 import { waitForPendingDraftWorktreeRequest } from "@/lib/worktrees/pendingDraftWorktree"
 import { waitForWorktreeBootstrap } from "@/lib/worktrees/worktreeBootstrap"
 import { getWorktreeSetupWaitEnabled } from "@/lib/openchamberConfig"
@@ -1713,33 +1714,19 @@ export const useSessionUIStore = create<SessionUIState>()((set, get) => ({
   getLastUserChoice: (sessionId) => {
     const directory = get().getDirectoryForSession(sessionId) ?? undefined
     const messages = getSyncMessages(sessionId, directory)
-    for (let i = messages.length - 1; i >= 0; i -= 1) {
-      const message = messages[i] as Message & {
-        model?: { providerID?: string; modelID?: string; variant?: string }
-        variant?: string
-        mode?: string
-      }
-      if (message.role !== "user") {
-        continue
-      }
-
-      const providerID = typeof message.model?.providerID === "string" && message.model.providerID.trim().length > 0
-        ? message.model.providerID
-        : undefined
-      const modelID = typeof message.model?.modelID === "string" && message.model.modelID.trim().length > 0
-        ? message.model.modelID
-        : undefined
-      const agent = typeof message.agent === "string" && message.agent.trim().length > 0
-        ? message.agent
-        : (typeof message.mode === "string" && message.mode.trim().length > 0 ? message.mode : undefined)
-      const variantCandidate = message.model?.variant ?? message.variant
-      const variant = typeof variantCandidate === "string" && variantCandidate.trim().length > 0
-        ? variantCandidate
-        : undefined
-
-      return { agent, providerID, modelID, variant }
+    const choice = findLatestUserModelChoice(
+      messages,
+      (messageId) => getSyncParts(messageId, directory),
+    )
+    if (!choice) {
+      return null
+    }
+    return {
+      agent: choice.agent,
+      providerID: choice.providerID,
+      modelID: choice.modelID,
+      variant: choice.variant,
     }
-    return null
   },
 
   getCurrentAgent: (sessionId) => {

From bcae0fcfc34018e951bca13b0c759ece12f9ad5d Mon Sep 17 00:00:00 2001
From: Bohdan Triapitsyn <artmore@protonmail.com>
Date: Tue, 4 Aug 2026 15:09:25 +0300
Subject: [PATCH 08/57] fix(walkthrough): stop the importance tag reading as a
 review finding
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The "Critical" pill was painted in the status-error colour, so a stop marked
because it drives the change read as a severity reported against the code —
the one thing this feature never does. It is now "Key change", carries its
emphasis with weight and an outline rather than a status colour, and both tags
state their meaning in a tooltip. The panel links the guide from its header,
and the guide gained a section on what the tags mean and what they do not.

Also corrects two German strings that translated the noun "stop" as the verb.
---
 packages/docs/content/docs/de/walkthrough.mdx | 14 +++++++++
 packages/docs/content/docs/walkthrough.mdx    | 14 +++++++++
 .../views/walkthrough/WalkthroughStream.tsx   | 29 +++++++++++++++----
 .../views/walkthrough/WalkthroughView.tsx     | 27 +++++++++++++++++
 packages/ui/src/lib/i18n/messages/de.ts       |  9 ++++--
 packages/ui/src/lib/i18n/messages/en.ts       |  5 +++-
 packages/ui/src/lib/i18n/messages/es.ts       |  5 +++-
 packages/ui/src/lib/i18n/messages/fr.ts       |  5 +++-
 packages/ui/src/lib/i18n/messages/ja.ts       |  5 +++-
 packages/ui/src/lib/i18n/messages/ko.ts       |  5 +++-
 packages/ui/src/lib/i18n/messages/pl.ts       |  5 +++-
 packages/ui/src/lib/i18n/messages/pt-BR.ts    |  5 +++-
 packages/ui/src/lib/i18n/messages/uk.ts       |  5 +++-
 packages/ui/src/lib/i18n/messages/zh-CN.ts    |  5 +++-
 packages/ui/src/lib/i18n/messages/zh-TW.ts    |  5 +++-
 15 files changed, 124 insertions(+), 19 deletions(-)

diff --git a/packages/docs/content/docs/de/walkthrough.mdx b/packages/docs/content/docs/de/walkthrough.mdx
index 04744a4f..e4be894b 100644
--- a/packages/docs/content/docs/de/walkthrough.mdx
+++ b/packages/docs/content/docs/de/walkthrough.mdx
@@ -11,6 +11,20 @@ Es erklärt und ordnet. Es bewertet Ihren Code nicht und fällt kein Urteil —
 
 Öffnen Sie es über das **Walkthrough**-Symbol in der rechten Leiste oder über die Schaltfläche **AI walkthrough** in den Bereichen Changes und Pull Request. Beides öffnet nur das Panel; generiert wird erst, wenn Sie **Generate walkthrough** drücken.
 
+## Wie ein Stop markiert ist
+
+Jeder Stop benennt sein Thema, erklärt es in ein bis zwei Sätzen und zeigt danach genau den Code, den er beschreibt. Manche Stops tragen eine kleine Markierung neben dem Titel:
+
+| Markierung | Bedeutung |
+| --- | --- |
+| **Kernänderung** | Dieser Stop trägt die eigentliche Änderung oder den größten Teil ihres Risikos. Lesen Sie ihn genau und zuerst. |
+| **Kontext** | Eine unterstützende Änderung, damit der Rest verständlich bleibt. Kann überflogen werden. |
+| *(ohne Markierung)* | Ein gewöhnlicher Schritt in der Lesereihenfolge. |
+
+Die Markierung sagt, **wo Sie Ihre Aufmerksamkeit investieren sollten**, und nichts über die Qualität des Codes. Ein Stop wird nie markiert, weil darin etwas Falsches gefunden wurde — das Walkthrough meldet keine Funde, keine Schweregrade und keine Urteile. Wenn Code bewertet werden soll, ist das die Aktion **Review** in [Git & GitHub](/git/).
+
+Die einzigen Markierungen, die tatsächlich auf ein Problem hinweisen, sind **Veraltet** und **Nicht abgedeckt** — und beide betreffen das Veralten des Walkthroughs selbst, nicht Ihren Code. Siehe unten.
+
 ## Was es prüfen kann
 
 | Bereich | Was enthalten ist |
diff --git a/packages/docs/content/docs/walkthrough.mdx b/packages/docs/content/docs/walkthrough.mdx
index 6d372bf5..742a47a0 100644
--- a/packages/docs/content/docs/walkthrough.mdx
+++ b/packages/docs/content/docs/walkthrough.mdx
@@ -11,6 +11,20 @@ It explains and orders. It does not judge your code or hand out verdicts — tha
 
 Open it from the **Walkthrough** icon in the right rail, or from the **AI walkthrough** button in the Changes and Pull Request panels. Both just open the panel; nothing is generated until you press **Generate walkthrough**.
 
+## How a stop is marked
+
+Each stop names what it is about, explains it in a sentence or two, and then shows exactly the code it describes. Some stops carry a small tag next to the title:
+
+| Tag | What it means |
+| --- | --- |
+| **Key change** | This stop drives the rest of the change, or carries most of its risk. Read it closely and read it first. |
+| **Context** | A supporting change, included so the rest makes sense. Safe to skim. |
+| *(no tag)* | An ordinary step in the reading order. |
+
+The tag is about **where to spend your attention**, not about the quality of the code. A stop is never marked because something was found wrong in it — the walkthrough reports no findings, no severities, and no verdicts. If you want code judged, that is the **Review** action in [Git & GitHub](/git/).
+
+The only marks that do report a problem are **Outdated** and **Not covered**, and both are about the walkthrough itself going out of date rather than about your code — see below.
+
 ## What it can review
 
 | Scope | What it covers |
diff --git a/packages/ui/src/components/views/walkthrough/WalkthroughStream.tsx b/packages/ui/src/components/views/walkthrough/WalkthroughStream.tsx
index 8b4e9f1c..bed04795 100644
--- a/packages/ui/src/components/views/walkthrough/WalkthroughStream.tsx
+++ b/packages/ui/src/components/views/walkthrough/WalkthroughStream.tsx
@@ -2,6 +2,7 @@ import { memo, useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { Icon } from '@/components/icon/Icon';
 import { FileTypeIcon } from '@/components/icons/FileTypeIcon';
 import { Button } from '@/components/ui/button';
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip';
 import { useI18n } from '@/lib/i18n';
 import { groupHunksByFile } from '@/lib/walkthrough/model';
 import type { WalkthroughStopView, WalkthroughView } from '@/lib/walkthrough/model';
@@ -20,8 +21,13 @@ interface WalkthroughStreamProps {
   wrapLines: boolean;
 }
 
+// Importance says where to spend attention, not what is wrong: a stop is marked
+// because it drives the rest of the change, never because something was found in
+// it. A red pill said the opposite — status colours are read as findings, and a
+// walkthrough deliberately hands out no verdicts — so the emphasis is carried by
+// weight and an outline instead, and the tooltip states the axis outright.
 const IMPORTANCE_CLASS: Record<WalkthroughStopImportance, string> = {
-  critical: 'bg-status-error/10 text-status-error',
+  critical: 'border border-[var(--interactive-border)] font-medium text-foreground',
   normal: 'bg-surface-muted text-muted-foreground',
   context: 'bg-surface-muted text-muted-foreground',
 };
@@ -41,11 +47,22 @@ const StopHeader = ({ stopView }: { stopView: WalkthroughStopView }) => {
             exactly as tall as one without: vertical padding on a smaller type
             size was pushing past the tallest element in the row. */}
         {stop.importance !== 'normal' && (
-          <span className={cn('typography-micro flex h-5 items-center rounded px-1.5 leading-none', IMPORTANCE_CLASS[stop.importance])}>
-            {stop.importance === 'critical'
-              ? t('walkthrough.importance.critical')
-              : t('walkthrough.importance.context')}
-          </span>
+          <Tooltip>
+            <TooltipTrigger
+              className={cn('typography-micro flex h-5 items-center rounded px-1.5 leading-none', IMPORTANCE_CLASS[stop.importance])}
+            >
+              {stop.importance === 'critical'
+                ? t('walkthrough.importance.critical')
+                : t('walkthrough.importance.context')}
+            </TooltipTrigger>
+            <TooltipContent className="max-w-64">
+              <p className="typography-micro leading-tight">
+                {stop.importance === 'critical'
+                  ? t('walkthrough.importance.criticalHint')
+                  : t('walkthrough.importance.contextHint')}
+              </p>
+            </TooltipContent>
+          </Tooltip>
         )}
       </div>
       <p className="typography-body text-muted-foreground">{stop.prose}</p>
diff --git a/packages/ui/src/components/views/walkthrough/WalkthroughView.tsx b/packages/ui/src/components/views/walkthrough/WalkthroughView.tsx
index 246a818c..00c8e6dd 100644
--- a/packages/ui/src/components/views/walkthrough/WalkthroughView.tsx
+++ b/packages/ui/src/components/views/walkthrough/WalkthroughView.tsx
@@ -10,7 +10,9 @@ import {
   DropdownMenuSeparator,
   DropdownMenuTrigger,
 } from '@/components/ui/dropdown-menu';
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip';
 import { useI18n, type Locale } from '@/lib/i18n';
+import { openExternalUrl } from '@/lib/url';
 import { buildWalkthroughView } from '@/lib/walkthrough/model';
 import type { WalkthroughSource, WalkthroughWorkingTreeScope } from '@/lib/walkthrough/types';
 import { ModelSelector } from '@/components/sections/agents/ModelSelector';
@@ -41,6 +43,12 @@ interface WalkthroughViewProps {
 
 const SCOPES: WalkthroughWorkingTreeScope[] = ['all', 'staged', 'working'];
 
+// What a walkthrough is — and what it deliberately is not — cannot be read off
+// the panel: the first question users asked about it was whether its marks were
+// review findings. The guide answers that, so it is reachable from the surface
+// itself rather than only from the release announcement.
+const WALKTHROUGH_GUIDE_URL = 'https://docs.openchamber.dev/walkthrough/';
+
 // DropdownMenuLabel defaults to the same size and weight as its items, which
 // makes a heading read as another choice. This matches SelectLabel, the
 // treatment used by the worktree picker.
@@ -524,6 +532,25 @@ export const WalkthroughView = ({ directory }: WalkthroughViewProps) => {
         </DropdownMenu>
 
         <div className="ml-auto flex min-w-0 items-center gap-1">
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <Button
+                type="button"
+                variant="ghost"
+                size="sm"
+                aria-label={t('walkthrough.help.guide')}
+                onClick={() => {
+                  void openExternalUrl(WALKTHROUGH_GUIDE_URL);
+                }}
+              >
+                <Icon name="question" className="size-4" />
+              </Button>
+            </TooltipTrigger>
+            <TooltipContent>
+              <p className="typography-micro leading-tight">{t('walkthrough.help.guide')}</p>
+            </TooltipContent>
+          </Tooltip>
+
           {/* A walkthrough nobody can read is worth nothing, so the prose
               language is a per-review choice like the model — defaulting to the
               interface language, which is the best evidence of what the reader
diff --git a/packages/ui/src/lib/i18n/messages/de.ts b/packages/ui/src/lib/i18n/messages/de.ts
index 0db76c86..4784df7b 100644
--- a/packages/ui/src/lib/i18n/messages/de.ts
+++ b/packages/ui/src/lib/i18n/messages/de.ts
@@ -2853,17 +2853,20 @@ export const dict = {
   'walkthrough.empty.title': 'Noch nichts vorhanden',
   'walkthrough.empty.description': 'Wählen Sie Inhalte aus, um einen Walkthrough zu erstellen.',
   'walkthrough.stale.banner': 'Der Code hat sich nach diesem Review geändert. Veraltete Schritte: {count}',
-  'walkthrough.stop.staleAll': 'Alle veralteten Inhalte stoppen',
+  'walkthrough.stop.staleAll': 'Der gesamte Code, den dieser Schritt beschrieben hat, hat sich geändert.',
   'walkthrough.stop.stalePartial': 'Ein Teil des vom Schritt beschriebenen Codes hat sich geändert. Fehlende Teile: {count}',
-  'walkthrough.stop.staleShort': 'Veraltete stoppen',
+  'walkthrough.stop.staleShort': 'Veraltet',
   'walkthrough.stop.noCode': 'Kein Code vorhanden',
   'walkthrough.uncovered.title': 'Vom Review ausgelassene Änderungen: {count}',
   'walkthrough.uncovered.description': 'Diese Bereiche wurden noch nicht in den Walkthrough aufgenommen.',
   'walkthrough.toc.moreFiles': 'Weitere Dateien: {count}',
   'walkthrough.toc.uncovered': 'Nicht abgedeckt: {count}',
   'walkthrough.toc.resize': 'Größe ändern',
-  'walkthrough.importance.critical': 'Kritisch',
+  'walkthrough.importance.critical': 'Kernänderung',
+  'walkthrough.importance.criticalHint': 'Dieser Schritt trägt die eigentliche Änderung, lesen Sie ihn genau. Es ist kein in Ihrem Code gefundenes Problem.',
   'walkthrough.importance.context': 'Kontext',
+  'walkthrough.importance.contextHint': 'Eine unterstützende Änderung, damit der Rest verständlich bleibt.',
+  'walkthrough.help.guide': 'So funktionieren Walkthroughs',
   'walkthrough.blocked.noModel.title': 'Kein Modell ausgewählt',
   'walkthrough.blocked.noModel.description': 'Wählen Sie zuerst ein Modell aus.',
   'walkthrough.blocked.emptyDiff.title': 'Kein Diff vorhanden',
diff --git a/packages/ui/src/lib/i18n/messages/en.ts b/packages/ui/src/lib/i18n/messages/en.ts
index 17d137e5..09cba1a6 100644
--- a/packages/ui/src/lib/i18n/messages/en.ts
+++ b/packages/ui/src/lib/i18n/messages/en.ts
@@ -1143,8 +1143,11 @@ export const dict = {
   'walkthrough.toc.moreFiles': 'More files: {count}',
   'walkthrough.toc.uncovered': 'Not covered: {count}',
   'walkthrough.toc.resize': 'Resize the contents column',
-  'walkthrough.importance.critical': 'Critical',
+  'walkthrough.importance.critical': 'Key change',
+  'walkthrough.importance.criticalHint': 'This step drives the rest of the change, so read it closely. It is not a problem found in your code.',
   'walkthrough.importance.context': 'Context',
+  'walkthrough.importance.contextHint': 'A supporting change, included so the rest makes sense.',
+  'walkthrough.help.guide': 'How walkthroughs work',
   'walkthrough.blocked.noModel.title': 'No small model available',
   'walkthrough.blocked.noModel.description': 'Sign in to a model provider to generate a review.',
   'walkthrough.blocked.emptyDiff.title': 'Nothing to review',
diff --git a/packages/ui/src/lib/i18n/messages/es.ts b/packages/ui/src/lib/i18n/messages/es.ts
index ea5086d0..dd514138 100644
--- a/packages/ui/src/lib/i18n/messages/es.ts
+++ b/packages/ui/src/lib/i18n/messages/es.ts
@@ -1144,8 +1144,11 @@ export const dict: Record<I18nKey, string> = {
   "walkthrough.toc.moreFiles": "Más archivos: {count}",
   "walkthrough.toc.uncovered": "Sin cubrir: {count}",
   "walkthrough.toc.resize": "Cambiar el ancho de la columna de contenidos",
-  "walkthrough.importance.critical": "Crítico",
+  "walkthrough.importance.critical": "Cambio clave",
+  "walkthrough.importance.criticalHint": "Este paso impulsa el resto del cambio, así que léelo con atención. No es un problema detectado en tu código.",
   "walkthrough.importance.context": "Contexto",
+  "walkthrough.importance.contextHint": "Un cambio de apoyo, incluido para que el resto tenga sentido.",
+  "walkthrough.help.guide": "Cómo funcionan los walkthroughs",
   "walkthrough.blocked.noModel.title": "No hay ningún modelo pequeño disponible",
   "walkthrough.blocked.noModel.description": "Inicia sesión en un proveedor de modelos para generar una revisión.",
   "walkthrough.blocked.emptyDiff.title": "Nada que revisar",
diff --git a/packages/ui/src/lib/i18n/messages/fr.ts b/packages/ui/src/lib/i18n/messages/fr.ts
index 3a625450..7bcdacee 100644
--- a/packages/ui/src/lib/i18n/messages/fr.ts
+++ b/packages/ui/src/lib/i18n/messages/fr.ts
@@ -968,8 +968,11 @@ export const dict = {
   'walkthrough.toc.moreFiles': 'Autres fichiers : {count}',
   'walkthrough.toc.uncovered': 'Non traité : {count}',
   'walkthrough.toc.resize': 'Redimensionner la colonne du sommaire',
-  'walkthrough.importance.critical': 'Critique',
+  'walkthrough.importance.critical': 'Changement clé',
+  'walkthrough.importance.criticalHint': "Cette étape porte l'essentiel du changement, lisez-la attentivement. Ce n'est pas un problème détecté dans votre code.",
   'walkthrough.importance.context': 'Contexte',
+  'walkthrough.importance.contextHint': 'Un changement de soutien, présent pour que le reste ait du sens.',
+  'walkthrough.help.guide': 'Comment fonctionnent les walkthroughs',
   'walkthrough.blocked.noModel.title': 'Aucun petit modèle disponible',
   'walkthrough.blocked.noModel.description': 'Connectez-vous à un fournisseur de modèles pour générer une revue.',
   'walkthrough.blocked.emptyDiff.title': 'Rien à examiner',
diff --git a/packages/ui/src/lib/i18n/messages/ja.ts b/packages/ui/src/lib/i18n/messages/ja.ts
index 181ec3e9..d344d9ae 100644
--- a/packages/ui/src/lib/i18n/messages/ja.ts
+++ b/packages/ui/src/lib/i18n/messages/ja.ts
@@ -1140,8 +1140,11 @@ export const dict: Record<I18nKey, string> = {
   'walkthrough.toc.moreFiles': 'その他のファイル: {count}',
   'walkthrough.toc.uncovered': '未対応: {count}',
   'walkthrough.toc.resize': '目次の列幅を変更',
-  'walkthrough.importance.critical': '重要',
+  'walkthrough.importance.critical': '主要な変更',
+  'walkthrough.importance.criticalHint': 'このステップが変更全体を動かしているため、じっくり読んでください。コードで見つかった問題ではありません。',
   'walkthrough.importance.context': '補足',
+  'walkthrough.importance.contextHint': '全体を理解するために添えられた補助的な変更です。',
+  'walkthrough.help.guide': 'ウォークスルーの仕組み',
   'walkthrough.blocked.noModel.title': '利用できるスモールモデルがありません',
   'walkthrough.blocked.noModel.description': 'レビューを生成するにはモデルプロバイダーにサインインしてください。',
   'walkthrough.blocked.emptyDiff.title': 'レビュー対象がありません',
diff --git a/packages/ui/src/lib/i18n/messages/ko.ts b/packages/ui/src/lib/i18n/messages/ko.ts
index 150a56ce..99244e62 100644
--- a/packages/ui/src/lib/i18n/messages/ko.ts
+++ b/packages/ui/src/lib/i18n/messages/ko.ts
@@ -1144,8 +1144,11 @@ export const dict: Record<I18nKey, string> = {
   'walkthrough.toc.moreFiles': '다른 파일: {count}',
   'walkthrough.toc.uncovered': '미포함: {count}',
   'walkthrough.toc.resize': '목차 열 너비 조절',
-  'walkthrough.importance.critical': '중요',
+  'walkthrough.importance.critical': '핵심 변경',
+  'walkthrough.importance.criticalHint': '이 단계가 변경 전체를 이끌고 있으니 꼼꼼히 읽어 보세요. 코드에서 발견된 문제가 아닙니다.',
   'walkthrough.importance.context': '참고',
+  'walkthrough.importance.contextHint': '나머지를 이해하는 데 도움이 되도록 함께 실은 보조 변경입니다.',
+  'walkthrough.help.guide': '워크스루 작동 방식',
   'walkthrough.blocked.noModel.title': '사용할 수 있는 스몰 모델이 없습니다',
   'walkthrough.blocked.noModel.description': '리뷰를 생성하려면 모델 제공자에 로그인하세요.',
   'walkthrough.blocked.emptyDiff.title': '리뷰할 내용이 없습니다',
diff --git a/packages/ui/src/lib/i18n/messages/pl.ts b/packages/ui/src/lib/i18n/messages/pl.ts
index 8f93e1f6..1dfa3db7 100644
--- a/packages/ui/src/lib/i18n/messages/pl.ts
+++ b/packages/ui/src/lib/i18n/messages/pl.ts
@@ -1456,8 +1456,11 @@ export const dict: Record<I18nKey, string> = {
   'walkthrough.toc.moreFiles': 'Więcej plików: {count}',
   'walkthrough.toc.uncovered': 'Nieuwzględnione: {count}',
   'walkthrough.toc.resize': 'Zmień szerokość kolumny spisu treści',
-  'walkthrough.importance.critical': 'Krytyczne',
+  'walkthrough.importance.critical': 'Kluczowa zmiana',
+  'walkthrough.importance.criticalHint': 'Ten krok napędza resztę zmiany, więc przeczytaj go uważnie. To nie jest problem znaleziony w Twoim kodzie.',
   'walkthrough.importance.context': 'Kontekst',
+  'walkthrough.importance.contextHint': 'Zmiana pomocnicza, dołączona po to, by reszta miała sens.',
+  'walkthrough.help.guide': 'Jak działają walkthroughy',
   'walkthrough.blocked.noModel.title': 'Brak dostępnego małego modelu',
   'walkthrough.blocked.noModel.description': 'Zaloguj się u dostawcy modeli, aby wygenerować przegląd.',
   'walkthrough.blocked.emptyDiff.title': 'Nie ma czego przeglądać',
diff --git a/packages/ui/src/lib/i18n/messages/pt-BR.ts b/packages/ui/src/lib/i18n/messages/pt-BR.ts
index 44fef67a..29cf2c9c 100644
--- a/packages/ui/src/lib/i18n/messages/pt-BR.ts
+++ b/packages/ui/src/lib/i18n/messages/pt-BR.ts
@@ -1144,8 +1144,11 @@ export const dict: Record<I18nKey, string> = {
   "walkthrough.toc.moreFiles": "Mais arquivos: {count}",
   "walkthrough.toc.uncovered": "Sem cobertura: {count}",
   "walkthrough.toc.resize": "Redimensionar a coluna de conteúdo",
-  "walkthrough.importance.critical": "Crítico",
+  "walkthrough.importance.critical": "Mudança principal",
+  "walkthrough.importance.criticalHint": "Este passo conduz o restante da mudança, então leia com atenção. Não é um problema encontrado no seu código.",
   "walkthrough.importance.context": "Contexto",
+  "walkthrough.importance.contextHint": "Uma mudança de apoio, incluída para que o restante faça sentido.",
+  "walkthrough.help.guide": "Como funcionam os walkthroughs",
   "walkthrough.blocked.noModel.title": "Nenhum modelo pequeno disponível",
   "walkthrough.blocked.noModel.description": "Entre em um provedor de modelos para gerar uma revisão.",
   "walkthrough.blocked.emptyDiff.title": "Nada para revisar",
diff --git a/packages/ui/src/lib/i18n/messages/uk.ts b/packages/ui/src/lib/i18n/messages/uk.ts
index c8663cea..f435acec 100644
--- a/packages/ui/src/lib/i18n/messages/uk.ts
+++ b/packages/ui/src/lib/i18n/messages/uk.ts
@@ -1144,8 +1144,11 @@ export const dict: Record<I18nKey, string> = {
   "walkthrough.toc.moreFiles": "Ще файлів: {count}",
   "walkthrough.toc.uncovered": "Не описано: {count}",
   "walkthrough.toc.resize": "Змінити ширину колонки змісту",
-  "walkthrough.importance.critical": "Критично",
+  "walkthrough.importance.critical": "Ключова зміна",
+  "walkthrough.importance.criticalHint": "Цей крок веде за собою решту зміни, тож прочитайте його уважно. Це не знайдена у вашому коді проблема.",
   "walkthrough.importance.context": "Контекст",
+  "walkthrough.importance.contextHint": "Допоміжна зміна, додана, щоб решта мала сенс.",
+  "walkthrough.help.guide": "Як працюють walkthrough",
   "walkthrough.blocked.noModel.title": "Немає доступної small model",
   "walkthrough.blocked.noModel.description": "Увійдіть до провайдера моделей, щоб створити розбір.",
   "walkthrough.blocked.emptyDiff.title": "Немає що оглядати",
diff --git a/packages/ui/src/lib/i18n/messages/zh-CN.ts b/packages/ui/src/lib/i18n/messages/zh-CN.ts
index 76ffac2f..f8789892 100644
--- a/packages/ui/src/lib/i18n/messages/zh-CN.ts
+++ b/packages/ui/src/lib/i18n/messages/zh-CN.ts
@@ -1144,8 +1144,11 @@ export const dict: Record<I18nKey, string> = {
   'walkthrough.toc.moreFiles': '其他文件：{count}',
   'walkthrough.toc.uncovered': '未涵盖：{count}',
   'walkthrough.toc.resize': '调整目录栏宽度',
-  'walkthrough.importance.critical': '关键',
+  'walkthrough.importance.critical': '关键改动',
+  'walkthrough.importance.criticalHint': '这一步带动了其余改动，值得仔细阅读。它不是在你的代码中发现的问题。',
   'walkthrough.importance.context': '背景',
+  'walkthrough.importance.contextHint': '辅助性的改动，列在这里是为了让其余部分说得通。',
+  'walkthrough.help.guide': 'Walkthrough 的工作方式',
   'walkthrough.blocked.noModel.title': '没有可用的小模型',
   'walkthrough.blocked.noModel.description': '请登录模型提供方后再生成评审。',
   'walkthrough.blocked.emptyDiff.title': '没有可评审的内容',
diff --git a/packages/ui/src/lib/i18n/messages/zh-TW.ts b/packages/ui/src/lib/i18n/messages/zh-TW.ts
index 3538d59c..bd475161 100644
--- a/packages/ui/src/lib/i18n/messages/zh-TW.ts
+++ b/packages/ui/src/lib/i18n/messages/zh-TW.ts
@@ -1156,8 +1156,11 @@ export const dict: Record<I18nKey, string> = {
   'walkthrough.toc.moreFiles': '其他檔案：{count}',
   'walkthrough.toc.uncovered': '未涵蓋：{count}',
   'walkthrough.toc.resize': '調整目錄欄寬度',
-  'walkthrough.importance.critical': '關鍵',
+  'walkthrough.importance.critical': '關鍵變更',
+  'walkthrough.importance.criticalHint': '這一步帶動了其餘變更，值得仔細閱讀。它不是在你的程式碼中發現的問題。',
   'walkthrough.importance.context': '背景',
+  'walkthrough.importance.contextHint': '輔助性的變更，列在這裡是為了讓其餘部分說得通。',
+  'walkthrough.help.guide': 'Walkthrough 的運作方式',
   'walkthrough.blocked.noModel.title': '沒有可用的小模型',
   'walkthrough.blocked.noModel.description': '請先登入模型供應商再產生審閱。',
   'walkthrough.blocked.emptyDiff.title': '沒有可審閱的內容',

From 8c37061886e010707dd7094593fd6829a3ee09ad Mon Sep 17 00:00:00 2001
From: Bohdan Triapitsyn <artmore@protonmail.com>
Date: Tue, 4 Aug 2026 15:15:47 +0300
Subject: [PATCH 09/57] fix(walkthrough): name an outdated server instead of
 failing to parse its HTML
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A server without these routes does not answer 404 with JSON. The unmatched
/api path reaches the OpenCode proxy, and OpenCode serves its embedded web UI
for anything it does not recognise — HTML, status 200 — so a client newer than
its server parsed a web page as JSON and put "Unexpected token '<', "<!doctype"
in the panel, naming neither the cause nor the remedy.

The client now checks the content type before parsing. A non-JSON answer on 2xx
or 404 blocks with "this server is older than the app, update it and refresh".
A non-JSON 5xx keeps its own failure: a server that answered badly is not a
server missing the feature, and sending that user to upgrade chases the wrong
thing.
---
 .../views/walkthrough/WalkthroughBlocker.tsx  | 10 ++-
 .../views/walkthrough/WalkthroughView.tsx     |  3 +
 packages/ui/src/lib/i18n/messages/de.ts       |  2 +
 packages/ui/src/lib/i18n/messages/en.ts       |  2 +
 packages/ui/src/lib/i18n/messages/es.ts       |  2 +
 packages/ui/src/lib/i18n/messages/fr.ts       |  2 +
 packages/ui/src/lib/i18n/messages/ja.ts       |  2 +
 packages/ui/src/lib/i18n/messages/ko.ts       |  2 +
 packages/ui/src/lib/i18n/messages/pl.ts       |  2 +
 packages/ui/src/lib/i18n/messages/pt-BR.ts    |  2 +
 packages/ui/src/lib/i18n/messages/uk.ts       |  2 +
 packages/ui/src/lib/i18n/messages/zh-CN.ts    |  2 +
 packages/ui/src/lib/i18n/messages/zh-TW.ts    |  2 +
 packages/ui/src/lib/walkthrough/api.test.ts   | 88 +++++++++++++++++++
 packages/ui/src/lib/walkthrough/api.ts        | 36 +++++++-
 packages/ui/src/lib/walkthrough/types.ts      | 10 ++-
 .../server/lib/walkthrough/DOCUMENTATION.md   | 15 ++++
 17 files changed, 178 insertions(+), 6 deletions(-)
 create mode 100644 packages/ui/src/lib/walkthrough/api.test.ts

diff --git a/packages/ui/src/components/views/walkthrough/WalkthroughBlocker.tsx b/packages/ui/src/components/views/walkthrough/WalkthroughBlocker.tsx
index a9a620ac..b0b521b4 100644
--- a/packages/ui/src/components/views/walkthrough/WalkthroughBlocker.tsx
+++ b/packages/ui/src/components/views/walkthrough/WalkthroughBlocker.tsx
@@ -6,10 +6,10 @@ import { useI18n } from '@/lib/i18n';
 import { useConfigStore } from '@/stores/useConfigStore';
 import { runtimeFetch } from '@/lib/runtime-fetch';
 import { updateDesktopSettings } from '@/lib/persistence';
-import type { WalkthroughBlockedReason, WalkthroughModel } from '@/lib/walkthrough/types';
+import type { WalkthroughBlockedState, WalkthroughModel } from '@/lib/walkthrough/types';
 
 interface WalkthroughBlockerProps {
-  reason: WalkthroughBlockedReason;
+  reason: WalkthroughBlockedState;
   model?: WalkthroughModel;
   requiredChars?: number;
   availableChars?: number;
@@ -102,6 +102,7 @@ export const WalkthroughBlocker = ({
     if (reason === 'no-model') return t('walkthrough.blocked.noModel.description');
     if (reason === 'empty-diff') return t('walkthrough.blocked.emptyDiff.description');
     if (reason === 'only-generated') return t('walkthrough.blocked.onlyGenerated.description');
+    if (reason === 'server-unsupported') return t('walkthrough.blocked.serverUnsupported.description');
     if (reason === 'output-exhausted') {
       return label
         ? t('walkthrough.blocked.outputExhausted.description', { model: label })
@@ -125,6 +126,7 @@ export const WalkthroughBlocker = ({
     if (reason === 'no-model') return t('walkthrough.blocked.noModel.title');
     if (reason === 'empty-diff') return t('walkthrough.blocked.emptyDiff.title');
     if (reason === 'only-generated') return t('walkthrough.blocked.onlyGenerated.title');
+    if (reason === 'server-unsupported') return t('walkthrough.blocked.serverUnsupported.title');
     if (reason === 'output-exhausted') return t('walkthrough.blocked.outputExhausted.title');
     if (reason === 'structured-output-unsupported') return t('walkthrough.blocked.structuredOutput.title');
     return t('walkthrough.blocked.contextTooSmall.title');
@@ -156,7 +158,9 @@ export const WalkthroughBlocker = ({
         </div>
       )}
 
-      {(reason === 'empty-diff' || reason === 'only-generated') && (
+      {/* Retry is the whole remedy once the server is updated, so it stays in
+          reach rather than sending the user back through the panel header. */}
+      {(reason === 'empty-diff' || reason === 'only-generated' || reason === 'server-unsupported') && (
         <Button type="button" variant="outline" size="sm" onClick={onRetry}>
           {t('walkthrough.action.refresh')}
         </Button>
diff --git a/packages/ui/src/components/views/walkthrough/WalkthroughView.tsx b/packages/ui/src/components/views/walkthrough/WalkthroughView.tsx
index 00c8e6dd..9934a276 100644
--- a/packages/ui/src/components/views/walkthrough/WalkthroughView.tsx
+++ b/packages/ui/src/components/views/walkthrough/WalkthroughView.tsx
@@ -440,6 +440,9 @@ export const WalkthroughView = ({ directory }: WalkthroughViewProps) => {
     || entry.error?.code === 'empty-diff'
     || entry.error?.code === 'only-generated'
     || entry.error?.code === 'output-exhausted'
+    // Client-detected rather than reported: the server answered something that
+    // was not JSON, so it has no walkthrough routes at all.
+    || entry.error?.code === 'server-unsupported'
     ? entry.error.code
     : entry.readiness && !entry.readiness.ready && !view
       && entry.readiness.reason !== 'no-provider-login'
diff --git a/packages/ui/src/lib/i18n/messages/de.ts b/packages/ui/src/lib/i18n/messages/de.ts
index 4784df7b..b6bd1b81 100644
--- a/packages/ui/src/lib/i18n/messages/de.ts
+++ b/packages/ui/src/lib/i18n/messages/de.ts
@@ -2881,6 +2881,8 @@ export const dict = {
   'walkthrough.blocked.outputExhausted.descriptionUnknownModel': 'Das kleine Modell hat sein gesamtes Ausgabelimit fürs Nachdenken verbraucht und nichts zurückgegeben. Denkende Modelle tun das bei großen Diffs oft — ein Modell, das weniger denkt, oder ein schmalerer Review-Bereich reicht eher aus.',
   'walkthrough.blocked.onlyGenerated.title': 'Nur generierter Inhalt',
   'walkthrough.blocked.onlyGenerated.description': 'Es ist nur generierter Inhalt vorhanden.',
+  'walkthrough.blocked.serverUnsupported.title': 'Dieser Server unterstützt keine Walkthroughs',
+  'walkthrough.blocked.serverUnsupported.description': 'Der OpenChamber-Server, mit dem diese App verbunden ist, hat die Walkthrough-API nicht beantwortet — er ist also älter als die App. Aktualisieren Sie den Server auf 1.18 oder neuer und aktualisieren Sie dann die Ansicht.',
   'walkthrough.blocked.contextTooSmall.descriptionUnknownModel': 'Das kleine Modell passt in etwa {available}K Zeichen, und dieser Diff braucht etwa {required}K. Nichts wird abgeschnitten — wähle stattdessen ein Modell mit größerem Kontext.',
   'walkthrough.blocked.structuredOutput.descriptionUnknownModel': 'Das kleine Modell unterstützt die strukturierten Antworten nicht, die ein Walkthrough benötigt.',
   'contextRail.surface.plan.description': 'Plankontext',
diff --git a/packages/ui/src/lib/i18n/messages/en.ts b/packages/ui/src/lib/i18n/messages/en.ts
index 09cba1a6..042c5cf8 100644
--- a/packages/ui/src/lib/i18n/messages/en.ts
+++ b/packages/ui/src/lib/i18n/messages/en.ts
@@ -1162,6 +1162,8 @@ export const dict = {
   'walkthrough.blocked.outputExhausted.descriptionUnknownModel': 'The small model spent its whole output allowance on reasoning and returned nothing. Reasoning models often do this on large diffs — a model that thinks less, or reviewing a narrower scope, will get through.',
   'walkthrough.blocked.onlyGenerated.title': 'Only generated files changed',
   'walkthrough.blocked.onlyGenerated.description': 'Every change here is a lockfile or other tool-produced output, which the review deliberately skips.',
+  'walkthrough.blocked.serverUnsupported.title': 'This server has no walkthrough support',
+  'walkthrough.blocked.serverUnsupported.description': 'The OpenChamber server this app is connected to did not answer the walkthrough API, which means it is older than the app. Update the server to 1.18 or newer, then refresh.',
   'walkthrough.blocked.contextTooSmall.descriptionUnknownModel': 'The small model fits about {available}K characters and this diff needs about {required}K. Nothing gets truncated — pick a model with a larger context instead.',
   'walkthrough.blocked.structuredOutput.descriptionUnknownModel': 'The small model does not support the structured responses a walkthrough needs.',
   'contextRail.surface.plan.description': 'View the current plan',
diff --git a/packages/ui/src/lib/i18n/messages/es.ts b/packages/ui/src/lib/i18n/messages/es.ts
index dd514138..6209796c 100644
--- a/packages/ui/src/lib/i18n/messages/es.ts
+++ b/packages/ui/src/lib/i18n/messages/es.ts
@@ -1163,6 +1163,8 @@ export const dict: Record<I18nKey, string> = {
   "walkthrough.blocked.outputExhausted.descriptionUnknownModel": "El modelo pequeño gastó todo su margen de salida razonando y no devolvió nada. Los modelos de razonamiento suelen hacerlo con diffs grandes: prueba con un modelo que razone menos o revisa un ámbito más reducido.",
   "walkthrough.blocked.onlyGenerated.title": "Solo cambiaron archivos generados",
   "walkthrough.blocked.onlyGenerated.description": "Todos los cambios son archivos de bloqueo u otra salida generada por herramientas, que la revisión omite a propósito.",
+  "walkthrough.blocked.serverUnsupported.title": "Este servidor no admite walkthroughs",
+  "walkthrough.blocked.serverUnsupported.description": "El servidor de OpenChamber al que está conectada esta app no respondió a la API de walkthrough, así que es más antiguo que la app. Actualiza el servidor a 1.18 o posterior y vuelve a intentarlo.",
   "walkthrough.blocked.contextTooSmall.descriptionUnknownModel": "El modelo pequeño admite unos {available} mil caracteres y este diff necesita unos {required} mil. No se recorta nada: elige un modelo con más contexto.",
   "walkthrough.blocked.structuredOutput.descriptionUnknownModel": "El modelo pequeño no admite las respuestas estructuradas que necesita un recorrido.",
   "contextRail.surface.plan.description": "Ver el plan actual",
diff --git a/packages/ui/src/lib/i18n/messages/fr.ts b/packages/ui/src/lib/i18n/messages/fr.ts
index 7bcdacee..09357712 100644
--- a/packages/ui/src/lib/i18n/messages/fr.ts
+++ b/packages/ui/src/lib/i18n/messages/fr.ts
@@ -987,6 +987,8 @@ export const dict = {
   'walkthrough.blocked.outputExhausted.descriptionUnknownModel': 'Le petit modèle a dépensé toute sa marge de sortie en raisonnement et n’a rien renvoyé. Les modèles de raisonnement le font souvent sur de gros diffs : essayez un modèle qui réfléchit moins, ou une portée plus étroite.',
   'walkthrough.blocked.onlyGenerated.title': 'Seuls des fichiers générés ont changé',
   'walkthrough.blocked.onlyGenerated.description': 'Toutes les modifications concernent des fichiers de verrouillage ou d’autres sorties générées, que la revue ignore délibérément.',
+  'walkthrough.blocked.serverUnsupported.title': 'Ce serveur ne prend pas en charge les walkthroughs',
+  'walkthrough.blocked.serverUnsupported.description': "Le serveur OpenChamber auquel cette application est connectée n'a pas répondu à l'API walkthrough : il est donc plus ancien que l'application. Mettez le serveur à jour en 1.18 ou plus récent, puis actualisez.",
   'walkthrough.blocked.contextTooSmall.descriptionUnknownModel': 'Le petit modèle accepte environ {available} k caractères et ce diff en demande environ {required} k. Rien n’est tronqué : choisissez un modèle au contexte plus large.',
   'walkthrough.blocked.structuredOutput.descriptionUnknownModel': 'Le petit modèle ne prend pas en charge les réponses structurées nécessaires à un parcours.',
   'contextRail.surface.plan.description': 'Voir le plan actuel',
diff --git a/packages/ui/src/lib/i18n/messages/ja.ts b/packages/ui/src/lib/i18n/messages/ja.ts
index d344d9ae..f8aab496 100644
--- a/packages/ui/src/lib/i18n/messages/ja.ts
+++ b/packages/ui/src/lib/i18n/messages/ja.ts
@@ -1159,6 +1159,8 @@ export const dict: Record<I18nKey, string> = {
   'walkthrough.blocked.outputExhausted.descriptionUnknownModel': 'スモールモデルは出力枠をすべて推論に使い、回答を返しませんでした。推論モデルは大きな差分でよくこうなります。推論の少ないモデルを選ぶか、対象範囲を絞ってください。',
   'walkthrough.blocked.onlyGenerated.title': '生成ファイルのみが変更されています',
   'walkthrough.blocked.onlyGenerated.description': 'ここでの変更はロックファイルなどツールが生成した出力だけで、レビューは意図的にこれらを対象外にしています。',
+  'walkthrough.blocked.serverUnsupported.title': 'このサーバーはウォークスルーに対応していません',
+  'walkthrough.blocked.serverUnsupported.description': 'このアプリが接続している OpenChamber サーバーはウォークスルー API に応答しませんでした。つまりアプリより古いバージョンです。サーバーを 1.18 以降に更新してから再読み込みしてください。',
   'walkthrough.blocked.contextTooSmall.descriptionUnknownModel': 'スモールモデルが扱えるのは約 {available} 千文字ですが、この差分には約 {required} 千文字が必要です。切り詰めは行いません。コンテキストの大きいモデルを選んでください。',
   'walkthrough.blocked.structuredOutput.descriptionUnknownModel': 'スモールモデルはウォークスルーに必要な構造化応答をサポートしていません。',
   'contextRail.surface.plan.description': '現在のプランを表示',
diff --git a/packages/ui/src/lib/i18n/messages/ko.ts b/packages/ui/src/lib/i18n/messages/ko.ts
index 99244e62..ee0e0464 100644
--- a/packages/ui/src/lib/i18n/messages/ko.ts
+++ b/packages/ui/src/lib/i18n/messages/ko.ts
@@ -1163,6 +1163,8 @@ export const dict: Record<I18nKey, string> = {
   'walkthrough.blocked.outputExhausted.descriptionUnknownModel': '스몰 모델이 출력 예산을 모두 추론에 쓰고 아무것도 반환하지 않았습니다. 추론 모델은 큰 diff에서 흔히 이렇게 됩니다. 덜 추론하는 모델을 고르거나 범위를 좁혀 보세요.',
   'walkthrough.blocked.onlyGenerated.title': '생성된 파일만 변경되었습니다',
   'walkthrough.blocked.onlyGenerated.description': '여기의 변경은 모두 잠금 파일이거나 도구가 만든 산출물이며, 리뷰는 이런 파일을 의도적으로 건너뜁니다.',
+  'walkthrough.blocked.serverUnsupported.title': '이 서버는 워크스루를 지원하지 않습니다',
+  'walkthrough.blocked.serverUnsupported.description': '이 앱이 연결된 OpenChamber 서버가 워크스루 API에 응답하지 않았습니다. 즉 앱보다 오래된 버전입니다. 서버를 1.18 이상으로 업데이트한 뒤 새로 고치세요.',
   'walkthrough.blocked.contextTooSmall.descriptionUnknownModel': '스몰 모델은 약 {available}천 자를 담을 수 있는데 이 diff에는 약 {required}천 자가 필요합니다. 잘라내지 않으니 컨텍스트가 더 큰 모델을 선택하세요.',
   'walkthrough.blocked.structuredOutput.descriptionUnknownModel': '스몰 모델은 워크스루에 필요한 구조화된 응답을 지원하지 않습니다.',
   'contextRail.surface.plan.description': '현재 계획 보기',
diff --git a/packages/ui/src/lib/i18n/messages/pl.ts b/packages/ui/src/lib/i18n/messages/pl.ts
index 1dfa3db7..120967fd 100644
--- a/packages/ui/src/lib/i18n/messages/pl.ts
+++ b/packages/ui/src/lib/i18n/messages/pl.ts
@@ -1475,6 +1475,8 @@ export const dict: Record<I18nKey, string> = {
   'walkthrough.blocked.outputExhausted.descriptionUnknownModel': 'Mały model zużył cały limit wyjścia na rozumowanie i nic nie zwrócił. Modele rozumujące często tak robią przy dużych różnicach — pomoże model mniej „myślący” albo węższy zakres przeglądu.',
   'walkthrough.blocked.onlyGenerated.title': 'Zmieniły się tylko pliki generowane',
   'walkthrough.blocked.onlyGenerated.description': 'Wszystkie zmiany to pliki blokad lub inne wyniki pracy narzędzi, które przegląd celowo pomija.',
+  'walkthrough.blocked.serverUnsupported.title': 'Ten serwer nie obsługuje walkthroughów',
+  'walkthrough.blocked.serverUnsupported.description': 'Serwer OpenChamber, z którym połączona jest ta aplikacja, nie odpowiedział na API walkthroughu — jest więc starszy niż aplikacja. Zaktualizuj serwer do wersji 1.18 lub nowszej i odśwież.',
   'walkthrough.blocked.contextTooSmall.descriptionUnknownModel': 'Mały model mieści około {available} tys. znaków, a te różnice potrzebują około {required} tys. Nic nie jest obcinane — wybierz model z większym kontekstem.',
   'walkthrough.blocked.structuredOutput.descriptionUnknownModel': 'Mały model nie obsługuje ustrukturyzowanych odpowiedzi wymaganych przez przewodnik.',
   'contextRail.surface.plan.description': 'Zobacz bieżący plan',
diff --git a/packages/ui/src/lib/i18n/messages/pt-BR.ts b/packages/ui/src/lib/i18n/messages/pt-BR.ts
index 29cf2c9c..c6fc84f4 100644
--- a/packages/ui/src/lib/i18n/messages/pt-BR.ts
+++ b/packages/ui/src/lib/i18n/messages/pt-BR.ts
@@ -1163,6 +1163,8 @@ export const dict: Record<I18nKey, string> = {
   "walkthrough.blocked.outputExhausted.descriptionUnknownModel": "O modelo pequeno gastou toda a margem de saída raciocinando e não devolveu nada. Modelos de raciocínio costumam fazer isso em diffs grandes — escolha um modelo que raciocine menos ou revise um escopo menor.",
   "walkthrough.blocked.onlyGenerated.title": "Só mudaram arquivos gerados",
   "walkthrough.blocked.onlyGenerated.description": "Todas as mudanças são arquivos de lock ou outra saída gerada por ferramentas, que a revisão ignora de propósito.",
+  "walkthrough.blocked.serverUnsupported.title": "Este servidor não oferece walkthroughs",
+  "walkthrough.blocked.serverUnsupported.description": "O servidor OpenChamber ao qual este app está conectado não respondeu à API de walkthrough, ou seja, é mais antigo que o app. Atualize o servidor para 1.18 ou mais recente e atualize a visualização.",
   "walkthrough.blocked.contextTooSmall.descriptionUnknownModel": "O modelo pequeno comporta cerca de {available} mil caracteres e este diff precisa de cerca de {required} mil. Nada é cortado — escolha um modelo com contexto maior.",
   "walkthrough.blocked.structuredOutput.descriptionUnknownModel": "O modelo pequeno não suporta as respostas estruturadas que um percurso exige.",
   "contextRail.surface.plan.description": "Ver o plano atual",
diff --git a/packages/ui/src/lib/i18n/messages/uk.ts b/packages/ui/src/lib/i18n/messages/uk.ts
index f435acec..803b791b 100644
--- a/packages/ui/src/lib/i18n/messages/uk.ts
+++ b/packages/ui/src/lib/i18n/messages/uk.ts
@@ -1163,6 +1163,8 @@ export const dict: Record<I18nKey, string> = {
   "walkthrough.blocked.outputExhausted.descriptionUnknownModel": "Small model витратила весь бюджет виводу на роздуми й нічого не повернула. Reasoning-моделі часто так поводяться на великих diff — допоможе модель, яка менше «думає», або вужча область огляду.",
   "walkthrough.blocked.onlyGenerated.title": "Змінились лише згенеровані файли",
   "walkthrough.blocked.onlyGenerated.description": "Усі зміни тут — це lock-файли чи інший результат роботи інструментів, які розбір свідомо пропускає.",
+  "walkthrough.blocked.serverUnsupported.title": "Цей сервер не підтримує walkthrough",
+  "walkthrough.blocked.serverUnsupported.description": "Сервер OpenChamber, до якого підключено застосунок, не відповів на walkthrough API — отже, він старіший за застосунок. Оновіть сервер до 1.18 або новішої версії та оновіть панель.",
   "walkthrough.blocked.contextTooSmall.descriptionUnknownModel": "Small model вміщає близько {available} тис. символів, а цьому diff потрібно близько {required} тис. Нічого не обрізається — оберіть модель із більшим контекстом.",
   "walkthrough.blocked.structuredOutput.descriptionUnknownModel": "Small model не підтримує структуровані відповіді, потрібні для розбору.",
   "contextRail.surface.plan.description": "Перегляд поточного плану",
diff --git a/packages/ui/src/lib/i18n/messages/zh-CN.ts b/packages/ui/src/lib/i18n/messages/zh-CN.ts
index f8789892..db955a7e 100644
--- a/packages/ui/src/lib/i18n/messages/zh-CN.ts
+++ b/packages/ui/src/lib/i18n/messages/zh-CN.ts
@@ -1163,6 +1163,8 @@ export const dict: Record<I18nKey, string> = {
   'walkthrough.blocked.outputExhausted.descriptionUnknownModel': '小模型把全部输出额度用在了推理上，没有返回结果。推理模型在大差异上经常如此——可以换一个少推理的模型，或缩小评审范围。',
   'walkthrough.blocked.onlyGenerated.title': '只有生成文件发生了改动',
   'walkthrough.blocked.onlyGenerated.description': '这里的改动全部是锁文件或其他工具生成的产物，评审会有意跳过它们。',
+  'walkthrough.blocked.serverUnsupported.title': '该服务器不支持 walkthrough',
+  'walkthrough.blocked.serverUnsupported.description': '此应用连接的 OpenChamber 服务器没有响应 walkthrough API，说明它比应用更旧。请将服务器升级到 1.18 或更高版本后刷新。',
   'walkthrough.blocked.contextTooSmall.descriptionUnknownModel': '小模型大约可容纳 {available} 千字符，而这份差异约需 {required} 千字符。我们不会截断内容，请改选上下文更大的模型。',
   'walkthrough.blocked.structuredOutput.descriptionUnknownModel': '小模型不支持导读所需的结构化响应。',
   'contextRail.surface.plan.description': '查看当前计划',
diff --git a/packages/ui/src/lib/i18n/messages/zh-TW.ts b/packages/ui/src/lib/i18n/messages/zh-TW.ts
index bd475161..13cbd616 100644
--- a/packages/ui/src/lib/i18n/messages/zh-TW.ts
+++ b/packages/ui/src/lib/i18n/messages/zh-TW.ts
@@ -1175,6 +1175,8 @@ export const dict: Record<I18nKey, string> = {
   'walkthrough.blocked.outputExhausted.descriptionUnknownModel': '小模型把全部輸出額度用在推理上，沒有回傳結果。推理模型在大型差異上經常如此——可以改用較少推理的模型，或縮小審閱範圍。',
   'walkthrough.blocked.onlyGenerated.title': '只有產生的檔案有變動',
   'walkthrough.blocked.onlyGenerated.description': '這裡的變更全部是鎖定檔或其他工具產生的輸出，審閱會刻意略過它們。',
+  'walkthrough.blocked.serverUnsupported.title': '該伺服器不支援 walkthrough',
+  'walkthrough.blocked.serverUnsupported.description': '此應用程式連線的 OpenChamber 伺服器沒有回應 walkthrough API，代表它比應用程式更舊。請將伺服器升級到 1.18 或更新版本後重新整理。',
   'walkthrough.blocked.contextTooSmall.descriptionUnknownModel': '小模型大約可容納 {available} 千字元，而這份差異約需 {required} 千字元。我們不會截斷內容，請改選上下文更大的模型。',
   'walkthrough.blocked.structuredOutput.descriptionUnknownModel': '小模型不支援導讀所需的結構化回應。',
   'contextRail.surface.plan.description': '檢視目前計畫',
diff --git a/packages/ui/src/lib/walkthrough/api.test.ts b/packages/ui/src/lib/walkthrough/api.test.ts
new file mode 100644
index 00000000..0ad57a7e
--- /dev/null
+++ b/packages/ui/src/lib/walkthrough/api.test.ts
@@ -0,0 +1,88 @@
+import { beforeEach, describe, expect, mock, test } from 'bun:test';
+
+// A server older than this client does not answer 404-with-JSON: unmatched
+// `/api/*` reaches the OpenCode proxy, and OpenCode serves its embedded web UI
+// for any unknown path — HTML, status 200. These tests pin that the panel gets
+// an actionable code instead of a JSON parser error.
+
+let nextResponse: Response = new Response('{}', { headers: { 'Content-Type': 'application/json' } });
+
+mock.module('@/lib/runtime-fetch', () => ({
+  runtimeFetch: mock(async () => nextResponse),
+}));
+
+const { fetchWalkthrough, generateWalkthrough } = await import('./api');
+const { WalkthroughError } = await import('./types');
+import type { WalkthroughSource } from './types';
+
+const SOURCE: WalkthroughSource = { kind: 'working-tree', scope: 'all' };
+
+const html = (status: number) =>
+  new Response('<!doctype html><html><body>OpenCode</body></html>', {
+    status,
+    headers: { 'Content-Type': 'text/html; charset=utf-8' },
+  });
+
+describe('walkthrough api', () => {
+  beforeEach(() => {
+    nextResponse = new Response('{}', { headers: { 'Content-Type': 'application/json' } });
+  });
+
+  test('reads a JSON answer', async () => {
+    nextResponse = new Response(JSON.stringify({ hunkCount: 3 }), {
+      headers: { 'Content-Type': 'application/json' },
+    });
+
+    const result = await fetchWalkthrough('/repo', SOURCE);
+
+    expect(result.hunkCount).toBe(3);
+  });
+
+  test('reports HTML served with 200 as a server without the routes', async () => {
+    nextResponse = html(200);
+
+    const error = await fetchWalkthrough('/repo', SOURCE).catch((caught: unknown) => caught);
+
+    expect(error).toBeInstanceOf(WalkthroughError);
+    expect((error as InstanceType<typeof WalkthroughError>).code).toBe('server-unsupported');
+    expect((error as Error).message).not.toContain('JSON');
+  });
+
+  test('reports a non-JSON 404 the same way', async () => {
+    nextResponse = html(404);
+
+    const error = await generateWalkthrough('/repo', SOURCE).catch((caught: unknown) => caught);
+
+    expect((error as InstanceType<typeof WalkthroughError>).code).toBe('server-unsupported');
+  });
+
+  test('keeps a server-side failure rather than blaming the server version', async () => {
+    nextResponse = new Response(JSON.stringify({ error: 'model exploded', code: 'output-exhausted' }), {
+      status: 500,
+      headers: { 'Content-Type': 'application/json' },
+    });
+
+    const error = await generateWalkthrough('/repo', SOURCE).catch((caught: unknown) => caught);
+
+    expect((error as InstanceType<typeof WalkthroughError>).code).toBe('output-exhausted');
+    expect((error as Error).message).toBe('model exploded');
+  });
+
+  test('a 5xx that is not JSON is a broken server, not a missing route', async () => {
+    nextResponse = html(502);
+
+    const error = await fetchWalkthrough('/repo', SOURCE).catch((caught: unknown) => caught);
+
+    expect((error as InstanceType<typeof WalkthroughError>).code).toBe(undefined);
+    expect((error as Error).message).toBe('Failed to load walkthrough');
+  });
+
+  test('JSON that does not parse is reported without the parser wording', async () => {
+    nextResponse = new Response('{"walkthrough":', { headers: { 'Content-Type': 'application/json' } });
+
+    const error = await fetchWalkthrough('/repo', SOURCE).catch((caught: unknown) => caught);
+
+    expect(error).toBeInstanceOf(WalkthroughError);
+    expect((error as Error).message).toBe('The server returned a malformed walkthrough response');
+  });
+});
diff --git a/packages/ui/src/lib/walkthrough/api.ts b/packages/ui/src/lib/walkthrough/api.ts
index 344bf853..ef06d2b0 100644
--- a/packages/ui/src/lib/walkthrough/api.ts
+++ b/packages/ui/src/lib/walkthrough/api.ts
@@ -16,9 +16,30 @@ interface ErrorPayload {
   availableChars?: unknown;
 }
 
+const isJsonResponse = (response: Response): boolean =>
+  /^application\/(?:[\w.+-]+\+)?json\b/i.test(response.headers.get('content-type') ?? '');
+
+/**
+ * A server without these routes does not answer 404 with JSON. Unmatched
+ * `/api/*` falls through to the OpenCode proxy, and OpenCode serves its embedded
+ * web UI for any path it does not know — HTML, status 200. Parsing that as JSON
+ * surfaced `Unexpected token '<', "<!doctype "...` in the panel, which names
+ * neither the cause nor the remedy.
+ *
+ * Only a missing route is reported this way: 2xx and 404 are the shapes it
+ * produces. A 5xx that is not JSON came from a server that did answer, so it
+ * keeps its own failure rather than becoming advice to upgrade.
+ */
+const serverUnsupported = () =>
+  new WalkthroughError('This OpenChamber server has no walkthrough API', { code: 'server-unsupported' });
+
+const looksUnsupported = (response: Response): boolean =>
+  !isJsonResponse(response) && (response.ok || response.status === 404);
+
 // An authoritative read that fails must never look like "there is nothing
 // here" — the caller would clear a perfectly good walkthrough off the screen.
 const throwFromResponse = async (response: Response, fallback: string): Promise<never> => {
+  if (looksUnsupported(response)) throw serverUnsupported();
   const payload = (await response.json().catch(() => null)) as ErrorPayload | null;
   throw new WalkthroughError(typeof payload?.error === 'string' ? payload.error : fallback, {
     code: typeof payload?.code === 'string' ? (payload.code as WalkthroughError['code']) : undefined,
@@ -28,6 +49,17 @@ const throwFromResponse = async (response: Response, fallback: string): Promise<
   });
 };
 
+const readJson = async <T>(response: Response): Promise<T> => {
+  if (!isJsonResponse(response)) throw serverUnsupported();
+  try {
+    return (await response.json()) as T;
+  } catch {
+    // Declared JSON, arrived truncated or empty: still not an answer, and the
+    // parser's own message says nothing a reader can act on.
+    throw new WalkthroughError('The server returned a malformed walkthrough response');
+  }
+};
+
 export async function fetchWalkthrough(
   directory: string,
   source: WalkthroughSource,
@@ -45,7 +77,7 @@ export async function fetchWalkthrough(
   if (!response.ok) {
     return throwFromResponse(response, 'Failed to load walkthrough');
   }
-  return response.json();
+  return readJson<WalkthroughResult>(response);
 }
 
 export async function generateWalkthrough(
@@ -68,7 +100,7 @@ export async function generateWalkthrough(
   if (!response.ok) {
     return throwFromResponse(response, 'Failed to generate walkthrough');
   }
-  return response.json();
+  return readJson<WalkthroughResult>(response);
 }
 
 /**
diff --git a/packages/ui/src/lib/walkthrough/types.ts b/packages/ui/src/lib/walkthrough/types.ts
index 5f8ef80a..e714a0ef 100644
--- a/packages/ui/src/lib/walkthrough/types.ts
+++ b/packages/ui/src/lib/walkthrough/types.ts
@@ -89,6 +89,7 @@ export interface WalkthroughResult {
  */
 export type WalkthroughStage = 'collecting' | 'asking' | 'retrying' | 'assembling';
 
+/** Reasons the server reports for refusing to generate. */
 export type WalkthroughBlockedReason =
   | 'no-model'
   | 'no-provider-login'
@@ -98,6 +99,13 @@ export type WalkthroughBlockedReason =
   | 'structured-output-unsupported'
   | 'output-exhausted';
 
+/**
+ * Everything the panel can render as a blocking screen. `server-unsupported` is
+ * never sent by a server — it is what the client concludes when the answer is
+ * not JSON at all, which is how a server too old to have these routes replies.
+ */
+export type WalkthroughBlockedState = WalkthroughBlockedReason | 'server-unsupported';
+
 export interface WalkthroughReadiness {
   ready: boolean;
   reason?: WalkthroughBlockedReason;
@@ -116,7 +124,7 @@ export interface WalkthroughReadiness {
 }
 
 export class WalkthroughError extends Error {
-  readonly code?: WalkthroughBlockedReason | 'invalid-walkthrough' | 'github-not-connected' | 'no-github-remote';
+  readonly code?: WalkthroughBlockedState | 'invalid-walkthrough' | 'github-not-connected' | 'no-github-remote';
   readonly model?: WalkthroughModel;
   readonly requiredChars?: number;
   readonly availableChars?: number;
diff --git a/packages/web/server/lib/walkthrough/DOCUMENTATION.md b/packages/web/server/lib/walkthrough/DOCUMENTATION.md
index 0f23fac5..abeb7e51 100644
--- a/packages/web/server/lib/walkthrough/DOCUMENTATION.md
+++ b/packages/web/server/lib/walkthrough/DOCUMENTATION.md
@@ -377,6 +377,21 @@ endpoint nothing calls is a maintenance surface that rots untested.
 Registered lazily from `feature-routes-runtime.js`. `/api/walkthrough` is in the
 JSON body-parser allowlist in `core-routes.js`.
 
+## A server that does not have these routes
+
+An `/api/*` path no OpenChamber route claims reaches the OpenCode proxy, and
+OpenCode answers any path it does not know with its embedded web UI — HTML, with
+status **200**. So a client newer than the server it is connected to is not told
+"no such route"; it is handed a web page. Parsing that as JSON is where
+`Unexpected token '<', "<!doctype "...` came from, a message that names neither
+the cause nor the remedy.
+
+The client therefore checks the content type before parsing. A non-JSON answer
+on 2xx or 404 becomes `server-unsupported`, which the panel renders as "this
+server is older than the app, update it". A non-JSON **5xx** keeps its own
+failure: a server that answered badly is not a server missing the feature, and
+telling someone to upgrade would send them after the wrong thing.
+
 ## Runtime availability
 
 Web, desktop, and hosted mobile reach these routes normally. VS Code serves Git

From 687681c83be2c93cc3ec6b20a6b7fdb7ae8875fc Mon Sep 17 00:00:00 2001
From: Bohdan Triapitsyn <artmore@protonmail.com>
Date: Tue, 4 Aug 2026 17:09:20 +0300
Subject: [PATCH 10/57] fix(providers): complete OAuth logins that finish in
 the browser
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

OpenCode's authorize response reports how the client must finish: `code`
expects a pasted code, while `auto` requires the client to call
oauth/callback immediately and hold it open — upstream blocks in there
polling for the device code or waiting on its loopback redirect, and only
that call persists the credential. Every auth plugin OpenCode ships uses
`auto`; none use `code`.

The page implemented only `code`. It opened the browser, showed a paste
field no provider can fill, and never called back, so a successful sign-in
stored nothing and the app sat unchanged. Authorization now drives the UI:
`auto` chains straight into the callback behind a waiting state with a
cancel, and the paste field appears only when a provider actually asks
for a code.

Two smaller failures shared that surface. Prompts were never collected,
which put GitHub Copilot Enterprise out of reach entirely, so a method
that declares them now asks first and passes the answers to authorize.
Device codes are also recovered from the instructions text, where they
actually live — the old code read fields the API does not return, so the
copy button never appeared.

The callback is exempt from the ordinary proxy deadline and gets a
15-minute budget, bounded by the shortest upstream expiry we know of.
A human sign-in with 2FA does not fit in four minutes, and expiring it
turned a completed login into a 504.
---
 .../providers/ProviderOAuthMethods.tsx        | 455 ++++++++++++++++++
 .../sections/providers/ProvidersPage.tsx      | 318 ++----------
 .../sections/providers/provider-oauth.test.ts | 236 +++++++++
 .../sections/providers/provider-oauth.ts      | 244 ++++++++++
 .../sections/providers/providerAuth.ts        |   2 +
 .../ui/src/lib/i18n/messages/de.settings.ts   |  15 +-
 .../ui/src/lib/i18n/messages/en.settings.ts   |  15 +-
 .../ui/src/lib/i18n/messages/es.settings.ts   |  15 +-
 .../ui/src/lib/i18n/messages/fr.settings.ts   |  15 +-
 .../ui/src/lib/i18n/messages/ja.settings.ts   |  15 +-
 .../ui/src/lib/i18n/messages/ko.settings.ts   |  15 +-
 .../ui/src/lib/i18n/messages/pl.settings.ts   |  15 +-
 .../src/lib/i18n/messages/pt-BR.settings.ts   |  15 +-
 .../ui/src/lib/i18n/messages/uk.settings.ts   |  15 +-
 .../src/lib/i18n/messages/zh-CN.settings.ts   |  15 +-
 .../src/lib/i18n/messages/zh-TW.settings.ts   |  15 +-
 .../web/server/lib/opencode/DOCUMENTATION.md  |   2 +
 packages/web/server/lib/opencode/proxy.js     |  24 +-
 packages/web/server/opencode-proxy.test.js    |  83 ++++
 19 files changed, 1239 insertions(+), 290 deletions(-)
 create mode 100644 packages/ui/src/components/sections/providers/ProviderOAuthMethods.tsx
 create mode 100644 packages/ui/src/components/sections/providers/provider-oauth.test.ts
 create mode 100644 packages/ui/src/components/sections/providers/provider-oauth.ts

diff --git a/packages/ui/src/components/sections/providers/ProviderOAuthMethods.tsx b/packages/ui/src/components/sections/providers/ProviderOAuthMethods.tsx
new file mode 100644
index 00000000..a293fdbe
--- /dev/null
+++ b/packages/ui/src/components/sections/providers/ProviderOAuthMethods.tsx
@@ -0,0 +1,455 @@
+import React from 'react';
+import { Button } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select';
+import { toast } from '@/components/ui';
+import { Icon } from '@/components/icon/Icon';
+import {
+  SETTINGS_SELECT_ROW_TRIGGER_CLASS,
+  SETTINGS_SELECT_SIZE,
+} from '@/components/sections/shared/SettingsSection';
+import { useI18n, type I18nKey } from '@/lib/i18n';
+import { cn } from '@/lib/utils';
+import { copyTextToClipboard } from '@/lib/clipboard';
+import { openExternalUrl } from '@/lib/url';
+import { opencodeClient } from '@/lib/opencode/client';
+import {
+  collectPromptInputs,
+  defaultPromptValues,
+  describeOAuthError,
+  firstUnansweredPrompt,
+  parseAuthPrompts,
+  parseAuthorization,
+  visiblePrompts,
+  type AuthPrompt,
+  type OAuthAuthorization,
+} from './provider-oauth';
+
+export interface ProviderOAuthMethod {
+  /** Index into the provider's full auth-method list, which is what OpenCode's `method` parameter addresses. */
+  index: number;
+  label: string;
+  prompts?: unknown;
+}
+
+interface ProviderOAuthMethodsProps {
+  providerId: string;
+  methods: ProviderOAuthMethod[];
+  /** Called once a credential has been stored, so the caller can reload providers. */
+  onConnected: () => void | Promise<void>;
+  /** Layout only — the caller owns separation from whatever sits above. */
+  className?: string;
+}
+
+type Flow =
+  | { phase: 'idle' }
+  | { phase: 'prompting'; methodIndex: number; prompts: AuthPrompt[]; error: string | null }
+  | { phase: 'authorizing'; methodIndex: number }
+  /** `auto`: the callback request is in flight and blocks until the browser sign-in finishes. */
+  | { phase: 'waiting'; methodIndex: number; authorization: OAuthAuthorization }
+  /** `code`: waiting for the user to paste a code out of the browser. */
+  | { phase: 'awaitingCode'; methodIndex: number; authorization: OAuthAuthorization; submitting: boolean }
+  | { phase: 'failed'; methodIndex: number; message: string };
+
+const IDLE: Flow = { phase: 'idle' };
+
+/**
+ * OAuth sign-in for a provider's auth methods.
+ *
+ * The completion method reported by `authorize` drives everything: `auto`
+ * chains straight into `callback` and holds it open until the user finishes in
+ * the browser, `code` collects a pasted code first. See `provider-oauth.ts`.
+ *
+ * Only one method can run at a time, and the in-flight callback is aborted when
+ * this component unmounts. Mount it with `key={providerId}` so switching
+ * providers starts from a clean flow.
+ */
+export const ProviderOAuthMethods: React.FC<ProviderOAuthMethodsProps> = ({
+  providerId,
+  methods,
+  onConnected,
+  className,
+}) => {
+  const { t } = useI18n();
+  const [flow, setFlow] = React.useState<Flow>(IDLE);
+  const [promptValues, setPromptValues] = React.useState<Record<string, string>>({});
+  const [codeInput, setCodeInput] = React.useState('');
+  const callbackAbortRef = React.useRef<AbortController | null>(null);
+
+  React.useEffect(() => () => callbackAbortRef.current?.abort(), []);
+
+  const activeIndex = flow.phase === 'idle' ? null : flow.methodIndex;
+  const busy = flow.phase === 'authorizing'
+    || flow.phase === 'waiting'
+    || (flow.phase === 'awaitingCode' && flow.submitting);
+
+  const copy = async (value: string, successKey: I18nKey, failureKey: I18nKey) => {
+    const result = await copyTextToClipboard(value);
+    if (result.ok) {
+      toast.success(t(successKey));
+      return;
+    }
+    console.error('Failed to copy OAuth value:', result.error);
+    toast.error(t(failureKey));
+  };
+
+  /**
+   * Runs the blocking half of the flow. Never throws: the caller has already
+   * handed control to the user, so a failure here is a flow state, not an
+   * exception to unwind.
+   */
+  const runCallback = async (methodIndex: number, code?: string) => {
+    const controller = new AbortController();
+    callbackAbortRef.current?.abort();
+    callbackAbortRef.current = controller;
+
+    try {
+      const result = await opencodeClient.getSdkClient().provider.oauth.callback(
+        {
+          providerID: providerId,
+          method: methodIndex,
+          ...(code ? { code } : {}),
+        },
+        { signal: controller.signal },
+      );
+      if (controller.signal.aborted) {
+        return;
+      }
+      if (result.error) {
+        throw result.error;
+      }
+
+      setFlow(IDLE);
+      toast.success(t('settings.providers.page.toast.oauthCompleted'));
+      await onConnected();
+    } catch (error) {
+      if (controller.signal.aborted) {
+        return;
+      }
+      console.error('Failed to complete OAuth flow:', error);
+      setFlow({
+        phase: 'failed',
+        methodIndex,
+        message: describeOAuthError(error, t, 'settings.providers.page.toast.oauthCompleteFailed'),
+      });
+    } finally {
+      if (callbackAbortRef.current === controller) {
+        callbackAbortRef.current = null;
+      }
+    }
+  };
+
+  const runAuthorize = async (methodIndex: number, inputs: Record<string, string>) => {
+    setFlow({ phase: 'authorizing', methodIndex });
+
+    let authorization: OAuthAuthorization;
+    try {
+      const result = await opencodeClient.getSdkClient().provider.oauth.authorize({
+        providerID: providerId,
+        method: methodIndex,
+        ...(Object.keys(inputs).length > 0 ? { inputs } : {}),
+      });
+      if (result.error) {
+        throw result.error;
+      }
+
+      const parsed = parseAuthorization(result.data);
+      if (!parsed) {
+        setFlow({
+          phase: 'failed',
+          methodIndex,
+          message: t('settings.providers.page.toast.oauthDetailsMissing'),
+        });
+        return;
+      }
+      authorization = parsed;
+    } catch (error) {
+      console.error('Failed to start OAuth flow:', error);
+      setFlow({
+        phase: 'failed',
+        methodIndex,
+        message: describeOAuthError(error, t, 'settings.providers.page.toast.oauthStartFailed'),
+      });
+      return;
+    }
+
+    if (authorization.url) {
+      void openExternalUrl(authorization.url);
+    }
+
+    if (authorization.method === 'code') {
+      setCodeInput('');
+      setFlow({ phase: 'awaitingCode', methodIndex, authorization, submitting: false });
+      return;
+    }
+
+    setFlow({ phase: 'waiting', methodIndex, authorization });
+    await runCallback(methodIndex);
+  };
+
+  const beginConnect = (method: ProviderOAuthMethod) => {
+    const prompts = parseAuthPrompts(method.prompts);
+    if (prompts.length === 0) {
+      void runAuthorize(method.index, {});
+      return;
+    }
+    setPromptValues(defaultPromptValues(prompts));
+    setFlow({ phase: 'prompting', methodIndex: method.index, prompts, error: null });
+  };
+
+  const submitPrompts = () => {
+    if (flow.phase !== 'prompting') {
+      return;
+    }
+    const unanswered = firstUnansweredPrompt(flow.prompts, promptValues);
+    if (unanswered) {
+      setFlow({
+        ...flow,
+        error: t('settings.providers.page.auth.oauth.promptRequired', { field: unanswered.message }),
+      });
+      return;
+    }
+    void runAuthorize(flow.methodIndex, collectPromptInputs(flow.prompts, promptValues));
+  };
+
+  const submitCode = () => {
+    if (flow.phase !== 'awaitingCode') {
+      return;
+    }
+    const code = codeInput.trim();
+    if (!code) {
+      return;
+    }
+    setFlow({ ...flow, submitting: true });
+    void runCallback(flow.methodIndex, code);
+  };
+
+  /**
+   * Stops tracking the attempt. Upstream keeps its pending authorization until
+   * a new `authorize` replaces it, so reconnecting is always safe.
+   */
+  const cancel = () => {
+    callbackAbortRef.current?.abort();
+    callbackAbortRef.current = null;
+    setFlow(IDLE);
+  };
+
+  const renderPrompt = (prompt: AuthPrompt) => {
+    const value = promptValues[prompt.key] ?? '';
+    const setValue = (next: string) =>
+      setPromptValues((prev) => ({ ...prev, [prompt.key]: next }));
+
+    return (
+      <div key={prompt.key} className="space-y-1.5">
+        <label className="typography-ui-label text-foreground">{prompt.message}</label>
+        {prompt.type === 'select' ? (
+          <Select value={value} onValueChange={setValue}>
+            <SelectTrigger size={SETTINGS_SELECT_SIZE} className={SETTINGS_SELECT_ROW_TRIGGER_CLASS}>
+              <SelectValue>
+                {(current) => prompt.options.find((option) => option.value === current)?.label ?? null}
+              </SelectValue>
+            </SelectTrigger>
+            <SelectContent>
+              {prompt.options.map((option) => (
+                <SelectItem key={option.value} value={option.value}>
+                  {option.hint ? `${option.label} · ${option.hint}` : option.label}
+                </SelectItem>
+              ))}
+            </SelectContent>
+          </Select>
+        ) : (
+          <Input
+            value={value}
+            onChange={(event) => setValue(event.target.value)}
+            placeholder={prompt.placeholder}
+            className="max-w-[24rem] text-xs"
+          />
+        )}
+      </div>
+    );
+  };
+
+  const renderAuthorizationDetails = (authorization: OAuthAuthorization) => (
+    <>
+      {authorization.instructions && (
+        <p className="typography-meta text-[var(--primary-base)] bg-[var(--primary-base)]/10 px-2 py-1.5 rounded">
+          {authorization.instructions}
+        </p>
+      )}
+
+      {authorization.userCode && (
+        <div className="flex items-center gap-2">
+          <Input
+            value={authorization.userCode}
+            readOnly
+            aria-label={t('settings.providers.page.auth.oauth.deviceCodeLabel')}
+            className="font-mono text-center tracking-widest"
+          />
+          <Button
+            variant="outline"
+            size="xs"
+            className="!font-normal shrink-0"
+            onClick={() => void copy(
+              authorization.userCode ?? '',
+              'settings.providers.page.toast.deviceCodeCopied',
+              'settings.providers.page.toast.deviceCodeCopyFailed',
+            )}
+          >
+            {t('settings.providers.page.actions.copyCode')}
+          </Button>
+        </div>
+      )}
+
+      {authorization.url && (
+        <div className="flex items-center gap-2">
+          <Input
+            value={authorization.url}
+            readOnly
+            aria-label={t('settings.providers.page.auth.oauth.linkLabel')}
+            className="text-xs text-muted-foreground"
+          />
+          <div className="flex gap-1 shrink-0">
+            <Button
+              variant="outline"
+              size="xs"
+              className="!font-normal"
+              onClick={() => void openExternalUrl(authorization.url ?? '')}
+            >
+              {t('settings.providers.page.actions.open')}
+            </Button>
+            <Button
+              variant="outline"
+              size="xs"
+              className="!font-normal"
+              onClick={() => void copy(
+                authorization.url ?? '',
+                'settings.providers.page.toast.oauthLinkCopied',
+                'settings.providers.page.toast.oauthLinkCopyFailed',
+              )}
+            >
+              {t('settings.providers.page.actions.copy')}
+            </Button>
+          </div>
+        </div>
+      )}
+    </>
+  );
+
+  return (
+    <div className={cn('space-y-4', className)}>
+      {methods.map((method) => {
+        const isActive = activeIndex === method.index;
+
+        return (
+          <div key={method.index} className="space-y-3">
+            <div className="flex items-center justify-between gap-2">
+              <div className="typography-ui-label text-foreground">{method.label}</div>
+              <Button
+                variant="outline"
+                size="xs"
+                className="!font-normal shrink-0"
+                onClick={() => beginConnect(method)}
+                disabled={busy}
+              >
+                {t('settings.providers.page.actions.connect')}
+              </Button>
+            </div>
+
+            {isActive && flow.phase === 'prompting' && (
+              <div className="space-y-3">
+                {visiblePrompts(flow.prompts, promptValues).map(renderPrompt)}
+                {flow.error && (
+                  <p className="typography-meta text-[var(--status-error)]">{flow.error}</p>
+                )}
+                <div className="flex items-center gap-2">
+                  <Button size="xs" className="!font-normal" onClick={submitPrompts}>
+                    {t('settings.providers.page.actions.continue')}
+                  </Button>
+                  <Button variant="ghost" size="xs" className="!font-normal" onClick={cancel}>
+                    {t('settings.providers.page.actions.cancel')}
+                  </Button>
+                </div>
+              </div>
+            )}
+
+            {isActive && flow.phase === 'authorizing' && (
+              <p className="typography-meta text-muted-foreground flex items-center gap-2">
+                <Icon name="loader" className="h-3.5 w-3.5 animate-spin" />
+                {t('settings.providers.page.auth.oauth.starting')}
+              </p>
+            )}
+
+            {isActive && flow.phase === 'waiting' && (
+              <div className="space-y-3">
+                {renderAuthorizationDetails(flow.authorization)}
+                <div className="flex items-center justify-between gap-2">
+                  <p className="typography-meta text-muted-foreground flex items-center gap-2">
+                    <Icon name="loader" className="h-3.5 w-3.5 animate-spin" />
+                    {t('settings.providers.page.auth.oauth.waiting')}
+                  </p>
+                  <Button variant="ghost" size="xs" className="!font-normal shrink-0" onClick={cancel}>
+                    {t('settings.providers.page.actions.cancel')}
+                  </Button>
+                </div>
+                <p className="typography-meta text-muted-foreground">
+                  {t('settings.providers.page.auth.oauth.waitingHint')}
+                </p>
+              </div>
+            )}
+
+            {isActive && flow.phase === 'awaitingCode' && (
+              <div className="space-y-3">
+                {renderAuthorizationDetails(flow.authorization)}
+                <p className="typography-meta text-muted-foreground">
+                  {t('settings.providers.page.auth.oauth.codeHint')}
+                </p>
+                <div className="flex items-center gap-2">
+                  <Input
+                    value={codeInput}
+                    onChange={(event) => setCodeInput(event.target.value)}
+                    placeholder={t('settings.providers.page.auth.pasteAuthorizationCodePlaceholder')}
+                    className="font-mono text-xs"
+                    disabled={flow.submitting}
+                  />
+                  <Button
+                    size="xs"
+                    className="!font-normal shrink-0"
+                    onClick={submitCode}
+                    disabled={flow.submitting || codeInput.trim().length === 0}
+                  >
+                    {flow.submitting
+                      ? t('settings.providers.page.actions.saving')
+                      : t('settings.providers.page.actions.complete')}
+                  </Button>
+                  <Button
+                    variant="ghost"
+                    size="xs"
+                    className="!font-normal shrink-0"
+                    onClick={cancel}
+                    disabled={flow.submitting}
+                  >
+                    {t('settings.providers.page.actions.cancel')}
+                  </Button>
+                </div>
+              </div>
+            )}
+
+            {isActive && flow.phase === 'failed' && (
+              <div className="space-y-2">
+                <p className="typography-meta text-[var(--status-error)]">{flow.message}</p>
+                <Button
+                  variant="outline"
+                  size="xs"
+                  className="!font-normal"
+                  onClick={() => beginConnect(method)}
+                >
+                  {t('settings.providers.page.actions.tryAgain')}
+                </Button>
+              </div>
+            )}
+          </div>
+        );
+      })}
+    </div>
+  );
+};
diff --git a/packages/ui/src/components/sections/providers/ProvidersPage.tsx b/packages/ui/src/components/sections/providers/ProvidersPage.tsx
index 008b04e2..a7594c1c 100644
--- a/packages/ui/src/components/sections/providers/ProvidersPage.tsx
+++ b/packages/ui/src/components/sections/providers/ProvidersPage.tsx
@@ -19,8 +19,6 @@ import { Icon } from "@/components/icon/Icon";
 import type { IconName } from "@/components/icon/icons";
 import { reloadOpenCodeConfiguration } from '@/stores/useAgentsStore';
 import { cn } from '@/lib/utils';
-import { copyTextToClipboard } from '@/lib/clipboard';
-import { openExternalUrl } from '@/lib/url';
 import type { ModelMetadata } from '@/types';
 import { getCurrentIntlLocale, useI18n } from '@/lib/i18n';
 import { runtimeFetch } from '@/lib/runtime-fetch';
@@ -31,8 +29,10 @@ import {
   parseAuthPayload,
   shouldShowApiKeyAuth,
   type AuthMethod,
+  type OAuthAuthMethodEntry,
 } from './providerAuth';
 import { CustomProviderForm } from './CustomProviderForm';
+import { ProviderOAuthMethods, type ProviderOAuthMethod } from './ProviderOAuthMethods';
 import {
   buildAuthSetRequest,
   buildProviderUpsertRequest,
@@ -85,6 +85,16 @@ interface ProviderSources {
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === 'object' && value !== null;
 
+const toOAuthMethods = (
+  entries: OAuthAuthMethodEntry[],
+  fallbackLabel: (index: number) => string,
+): ProviderOAuthMethod[] =>
+  entries.map(({ method, methodIndex }) => ({
+    index: methodIndex,
+    label: method.label || method.name || fallbackLabel(methodIndex),
+    prompts: method.prompts,
+  }));
+
 const normalizeProviderEntry = (entry: unknown): ProviderOption | null => {
   if (typeof entry === 'string') {
     return { id: entry };
@@ -147,9 +157,6 @@ export const ProvidersPage: React.FC = () => {
   const [apiKeyInputs, setApiKeyInputs] = React.useState<Record<string, string>>({});
   const [authBusyKey, setAuthBusyKey] = React.useState<string | null>(null);
   const [modelQuery, setModelQuery] = React.useState('');
-  const [pendingOAuth, setPendingOAuth] = React.useState<{ providerId: string; methodIndex: number } | null>(null);
-  const [oauthCodes, setOauthCodes] = React.useState<Record<string, string>>({});
-  const [oauthDetails, setOauthDetails] = React.useState<Record<string, { url?: string; instructions?: string; userCode?: string }>>({});
   const [availableProviders, setAvailableProviders] = React.useState<ProviderOption[]>([]);
   const [availableLoading, setAvailableLoading] = React.useState(false);
   const [availableError, setAvailableError] = React.useState<string | null>(null);
@@ -181,7 +188,8 @@ export const ProvidersPage: React.FC = () => {
   React.useEffect(() => {
     // Auth methods drive which credential UI to show (API key vs OAuth). Keep
     // them loaded for the active provider view so OAuth-only plugins never fall
-    // back to an API key form merely because methods were never fetched.
+    // back to an API key form merely because methods were never fetched, and so
+    // an already-listed provider can still offer re-authentication.
     if (!selectedProviderId) {
       return;
     }
@@ -458,117 +466,13 @@ export const ProvidersPage: React.FC = () => {
     }
   };
 
-  const handleOAuthStart = async (providerId: string, methodIndex: number) => {
-    const busyKey = `oauth:${providerId}:${methodIndex}`;
-    setAuthBusyKey(busyKey);
+  const oauthMethodFallbackLabel = (index: number) =>
+    t('settings.providers.page.auth.oauthMethodFallback', { index: String(index + 1) });
 
-    try {
-      const result = await opencodeClient.getSdkClient().provider.oauth.authorize({
-        providerID: providerId,
-        method: methodIndex,
-      });
-      if (result.error) {
-        throw new Error(t('settings.providers.page.toast.oauthStartFailed'));
-      }
-
-      const payloadRecord: Record<string, unknown> = isRecord(result.data) ? result.data : {};
-      const nestedData = payloadRecord.data;
-      const dataRecord: Record<string, unknown> = isRecord(nestedData) ? nestedData : payloadRecord;
-      const urlCandidate =
-        (typeof dataRecord.url === 'string' && dataRecord.url) ||
-        (typeof dataRecord.verification_uri_complete === 'string' && dataRecord.verification_uri_complete) ||
-        (typeof dataRecord.verification_uri === 'string' && dataRecord.verification_uri) ||
-        undefined;
-      const instructions =
-        (typeof dataRecord.instructions === 'string' && dataRecord.instructions) ||
-        (typeof dataRecord.message === 'string' && dataRecord.message) ||
-        undefined;
-      const userCode =
-        (typeof dataRecord.user_code === 'string' && dataRecord.user_code) ||
-        (typeof dataRecord.code === 'string' && dataRecord.code) ||
-        (typeof dataRecord.userCode === 'string' && dataRecord.userCode) ||
-        undefined;
-
-      if (!urlCandidate && !instructions && !userCode) {
-        throw new Error(t('settings.providers.page.toast.oauthDetailsMissing'));
-      }
-
-      const detailsKey = `${providerId}:${methodIndex}`;
-      setOauthDetails((prev) => ({
-        ...prev,
-        [detailsKey]: {
-          url: urlCandidate,
-          instructions,
-          userCode,
-        },
-      }));
-
-      if (urlCandidate) {
-        void openExternalUrl(urlCandidate);
-      }
-      setPendingOAuth({ providerId, methodIndex });
-      toast.message(t('settings.providers.page.toast.completeOAuthInBrowser'));
-    } catch (error) {
-      console.error('Failed to start OAuth flow:', error);
-      toast.error(t('settings.providers.page.toast.oauthStartFailed'));
-    } finally {
-      setAuthBusyKey(null);
-    }
-  };
-
-  const handleOAuthComplete = async (providerId: string, methodIndex: number) => {
-    const codeKey = `${providerId}:${methodIndex}`;
-    const code = oauthCodes[codeKey]?.trim();
-
-    const busyKey = `oauth-complete:${providerId}:${methodIndex}`;
-    setAuthBusyKey(busyKey);
-
-    try {
-      const requestBody: { method: number; code?: string } = { method: methodIndex };
-      if (code) {
-        requestBody.code = code;
-      }
-
-      const result = await opencodeClient.getSdkClient().provider.oauth.callback({
-        providerID: providerId,
-        method: requestBody.method,
-        code: requestBody.code,
-      });
-      if (result.error) {
-        throw new Error(t('settings.providers.page.toast.oauthCompleteFailed'));
-      }
-
-      toast.success(t('settings.providers.page.toast.oauthCompleted'));
-      setOauthCodes((prev) => ({ ...prev, [codeKey]: '' }));
-      setPendingOAuth(null);
-      await reloadOpenCodeConfiguration({ scopes: ["providers"], mode: "active" });
-      setSelectedProvider(providerId);
-    } catch (error) {
-      console.error('Failed to complete OAuth flow:', error);
-      toast.error(t('settings.providers.page.toast.oauthCompleteFailed'));
-    } finally {
-      setAuthBusyKey(null);
-    }
-  };
-
-  const handleCopyOAuthLink = async (url: string) => {
-    const result = await copyTextToClipboard(url);
-    if (result.ok) {
-      toast.success(t('settings.providers.page.toast.oauthLinkCopied'));
-      return;
-    }
-    console.error('Failed to copy OAuth link:', result.error);
-    toast.error(t('settings.providers.page.toast.oauthLinkCopyFailed'));
-  };
-
-  const handleCopyOAuthCode = async (code: string) => {
-    const result = await copyTextToClipboard(code);
-    if (result.ok) {
-      toast.success(t('settings.providers.page.toast.deviceCodeCopied'));
-      return;
-    }
-    console.error('Failed to copy device code:', result.error);
-    toast.error(t('settings.providers.page.toast.deviceCodeCopyFailed'));
+  const handleOAuthConnected = async (providerId: string) => {
+    setShowAuthPanel(false);
+    await reloadOpenCodeConfiguration({ scopes: ['providers'], mode: 'active' });
+    setSelectedProvider(providerId);
   };
 
   const handleDisconnectProvider = async (providerId: string) => {
@@ -777,7 +681,10 @@ export const ProvidersPage: React.FC = () => {
                 <>
                   {(() => {
                     const candidateAuthMethods = authMethodsByProvider[candidateProviderId] ?? [];
-                    const candidateOAuthMethods = getOAuthAuthMethods(candidateAuthMethods);
+                    const candidateOAuthMethods = toOAuthMethods(
+                      getOAuthAuthMethods(candidateAuthMethods),
+                      oauthMethodFallbackLabel,
+                    );
                     const showApiKey = shouldShowApiKeyAuth(candidateAuthMethods);
 
                     return (
@@ -814,85 +721,13 @@ export const ProvidersPage: React.FC = () => {
                         ) : null}
 
                         {candidateOAuthMethods.length > 0 ? (
-                          <div className={cn('space-y-4', showApiKey && 'border-t border-[var(--surface-subtle)] pt-2')}>
-                            {candidateOAuthMethods.map(({ method, methodIndex }) => {
-                              const methodLabel = method.label || method.name || t('settings.providers.page.auth.oauthMethodFallback', { index: String(methodIndex + 1) });
-                              const codeKey = `${candidateProviderId}:${methodIndex}`;
-                              const isPending =
-                                pendingOAuth?.providerId === candidateProviderId && pendingOAuth?.methodIndex === methodIndex;
-
-                              return (
-                                <div key={`${candidateProviderId}-${methodIndex}-${methodLabel}`} className="space-y-3">
-                                  <div className="flex items-center justify-between gap-2">
-                                    <div>
-                                      <div className="typography-ui-label text-foreground">{methodLabel}</div>
-                                      {(method.description || method.help) && (
-                                        <div className="typography-meta text-muted-foreground">
-                                          {String(method.description || method.help)}
-                                        </div>
-                                      )}
-                                    </div>
-                                    <Button
-                                      variant="outline"
-                                      size="xs"
-                                      className="!font-normal"
-                                      onClick={() => handleOAuthStart(candidateProviderId, methodIndex)}
-                                      disabled={authBusyKey === `oauth:${candidateProviderId}:${methodIndex}`}
-                                    >
-                                      {t('settings.providers.page.actions.connect')}
-                                    </Button>
-                                  </div>
-
-                                  {oauthDetails[codeKey]?.instructions && (
-                                    <p className="typography-meta text-[var(--primary-base)] bg-[var(--primary-base)]/10 px-2 py-1.5 rounded">
-                                      {oauthDetails[codeKey]?.instructions}
-                                    </p>
-                                  )}
-
-                                  {oauthDetails[codeKey]?.userCode && (
-                                    <div className="flex items-center gap-2 mt-2">
-                                      <Input value={oauthDetails[codeKey]?.userCode} readOnly className="font-mono text-center tracking-widest" />
-                                      <Button variant="outline" size="xs" className="!font-normal" onClick={() => handleCopyOAuthCode(oauthDetails[codeKey]?.userCode ?? '')}>{t('settings.providers.page.actions.copyCode')}</Button>
-                                    </div>
-                                  )}
-
-                                  {oauthDetails[codeKey]?.url && (
-                                    <div className="flex items-center gap-2 mt-2">
-                                      <Input value={oauthDetails[codeKey]?.url} readOnly className="text-xs text-muted-foreground" />
-                                      <div className="flex gap-1 shrink-0">
-                                        <Button variant="outline" size="xs" className="!font-normal" onClick={() => openExternalUrl(oauthDetails[codeKey]?.url ?? '')}>{t('settings.providers.page.actions.open')}</Button>
-                                        <Button variant="outline" size="xs" className="!font-normal" onClick={() => handleCopyOAuthLink(oauthDetails[codeKey]?.url ?? '')}>{t('settings.providers.page.actions.copy')}</Button>
-                                      </div>
-                                    </div>
-                                  )}
-
-                                  {isPending && (
-                                    <div className="flex items-center gap-2 mt-2">
-                                      <Input
-                                        value={oauthCodes[codeKey] ?? ''}
-                                        onChange={(event) =>
-                                          setOauthCodes((prev) => ({
-                                            ...prev,
-                                            [codeKey]: event.target.value,
-                                          }))
-                                        }
-                                        placeholder={t('settings.providers.page.auth.pasteAuthorizationCodePlaceholder')}
-                                        className="font-mono text-xs"
-                                      />
-                                      <Button
-                                        size="xs"
-                                        className="!font-normal"
-                                        onClick={() => handleOAuthComplete(candidateProviderId, methodIndex)}
-                                        disabled={authBusyKey === `oauth-complete:${candidateProviderId}:${methodIndex}`}
-                                      >
-                                        {authBusyKey === `oauth-complete:${candidateProviderId}:${methodIndex}` ? t('settings.providers.page.actions.saving') : t('settings.providers.page.actions.complete')}
-                                      </Button>
-                                    </div>
-                                  )}
-                                </div>
-                              );
-                            })}
-                          </div>
+                          <ProviderOAuthMethods
+                            key={candidateProviderId}
+                            providerId={candidateProviderId}
+                            methods={candidateOAuthMethods}
+                            onConnected={() => handleOAuthConnected(candidateProviderId)}
+                            className={cn(showApiKey && 'border-t border-[var(--surface-subtle)] pt-2')}
+                          />
                         ) : null}
                       </>
                     );
@@ -919,7 +754,10 @@ export const ProvidersPage: React.FC = () => {
 
   const providerModels = Array.isArray(selectedProvider.models) ? selectedProvider.models : [];
   const providerAuthMethods = authMethodsByProvider[selectedProvider.id] ?? [];
-  const oauthAuthMethods = getOAuthAuthMethods(providerAuthMethods);
+  const oauthAuthMethods = toOAuthMethods(
+    getOAuthAuthMethods(providerAuthMethods),
+    oauthMethodFallbackLabel,
+  );
   const showApiKeyAuth = shouldShowApiKeyAuth(providerAuthMethods);
   const sourcesLoaded = Boolean(selectedSources);
   const isEditableCustomProvider = sourcesLoaded
@@ -1062,85 +900,13 @@ export const ProvidersPage: React.FC = () => {
                 ) : null}
 
                 {oauthAuthMethods.length > 0 && (
-                  <div className={cn('space-y-4', showApiKeyAuth && 'border-t border-[var(--surface-subtle)] pt-2')}>
-                    {oauthAuthMethods.map(({ method, methodIndex }) => {
-                      const methodLabel = method.label || method.name || t('settings.providers.page.auth.oauthMethodFallback', { index: String(methodIndex + 1) });
-                      const codeKey = `${selectedProvider.id}:${methodIndex}`;
-                      const isPending =
-                        pendingOAuth?.providerId === selectedProvider.id && pendingOAuth?.methodIndex === methodIndex;
-
-                      return (
-                        <div key={`${selectedProvider.id}-${methodIndex}-${methodLabel}`} className="space-y-3">
-                          <div className="flex items-center justify-between gap-2">
-                            <div>
-                              <div className="typography-ui-label text-foreground">{methodLabel}</div>
-                              {(method.description || method.help) && (
-                                <div className="typography-meta text-muted-foreground">
-                                  {String(method.description || method.help)}
-                                </div>
-                              )}
-                            </div>
-                            <Button
-                              variant="outline"
-                              size="xs"
-                              className="!font-normal"
-                              onClick={() => handleOAuthStart(selectedProvider.id, methodIndex)}
-                              disabled={authBusyKey === `oauth:${selectedProvider.id}:${methodIndex}`}
-                            >
-                              {t('settings.providers.page.actions.connect')}
-                            </Button>
-                          </div>
-
-                          {oauthDetails[codeKey]?.instructions && (
-                            <p className="typography-meta text-[var(--primary-base)] bg-[var(--primary-base)]/10 px-2 py-1.5 rounded">
-                              {oauthDetails[codeKey]?.instructions}
-                            </p>
-                          )}
-
-                          {oauthDetails[codeKey]?.userCode && (
-                            <div className="flex items-center gap-2 mt-2">
-                              <Input value={oauthDetails[codeKey]?.userCode} readOnly className="font-mono text-center tracking-widest" />
-                              <Button variant="outline" size="xs" className="!font-normal" onClick={() => handleCopyOAuthCode(oauthDetails[codeKey]?.userCode ?? '')}>{t('settings.providers.page.actions.copyCode')}</Button>
-                            </div>
-                          )}
-
-                          {oauthDetails[codeKey]?.url && (
-                            <div className="flex items-center gap-2 mt-2">
-                              <Input value={oauthDetails[codeKey]?.url} readOnly className="text-xs text-muted-foreground" />
-                              <div className="flex gap-1 shrink-0">
-                                <Button variant="outline" size="xs" className="!font-normal" onClick={() => openExternalUrl(oauthDetails[codeKey]?.url ?? '')}>{t('settings.providers.page.actions.open')}</Button>
-                                <Button variant="outline" size="xs" className="!font-normal" onClick={() => handleCopyOAuthLink(oauthDetails[codeKey]?.url ?? '')}>{t('settings.providers.page.actions.copy')}</Button>
-                              </div>
-                            </div>
-                          )}
-
-                          {isPending && (
-                            <div className="flex items-center gap-2 mt-2">
-                              <Input
-                                value={oauthCodes[codeKey] ?? ''}
-                                onChange={(event) =>
-                                  setOauthCodes((prev) => ({
-                                    ...prev,
-                                    [codeKey]: event.target.value,
-                                  }))
-                                }
-                                placeholder={t('settings.providers.page.auth.pasteAuthorizationCodePlaceholder')}
-                                className="font-mono text-xs"
-                              />
-                              <Button
-                                size="xs"
-                                className="!font-normal"
-                                onClick={() => handleOAuthComplete(selectedProvider.id, methodIndex)}
-                                disabled={authBusyKey === `oauth-complete:${selectedProvider.id}:${methodIndex}`}
-                              >
-                                {authBusyKey === `oauth-complete:${selectedProvider.id}:${methodIndex}` ? t('settings.providers.page.actions.saving') : t('settings.providers.page.actions.complete')}
-                              </Button>
-                            </div>
-                          )}
-                        </div>
-                      );
-                    })}
-                  </div>
+                  <ProviderOAuthMethods
+                    key={selectedProvider.id}
+                    providerId={selectedProvider.id}
+                    methods={oauthAuthMethods}
+                    onConnected={() => handleOAuthConnected(selectedProvider.id)}
+                    className={cn(showApiKeyAuth && 'border-t border-[var(--surface-subtle)] pt-2')}
+                  />
                 )}
               </div>
             )}
diff --git a/packages/ui/src/components/sections/providers/provider-oauth.test.ts b/packages/ui/src/components/sections/providers/provider-oauth.test.ts
new file mode 100644
index 00000000..93f8e762
--- /dev/null
+++ b/packages/ui/src/components/sections/providers/provider-oauth.test.ts
@@ -0,0 +1,236 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  collectPromptInputs,
+  defaultPromptValues,
+  describeOAuthError,
+  firstUnansweredPrompt,
+  isPromptVisible,
+  parseAuthPrompts,
+  parseAuthorization,
+  visiblePrompts,
+  type AuthPrompt,
+  type ProviderOAuthTranslator,
+} from './provider-oauth';
+
+/** Mirrors the github-copilot auth method shipped by OpenCode. */
+const copilotPrompts = [
+  {
+    type: 'select',
+    key: 'deploymentType',
+    message: 'Select GitHub deployment type',
+    options: [
+      { label: 'GitHub.com', value: 'github.com', hint: 'Public' },
+      { label: 'GitHub Enterprise', value: 'enterprise' },
+    ],
+  },
+  {
+    type: 'text',
+    key: 'enterpriseUrl',
+    message: 'Enter your GitHub Enterprise URL or domain',
+    placeholder: 'company.ghe.com',
+    when: { key: 'deploymentType', op: 'eq', value: 'enterprise' },
+  },
+];
+
+describe('parseAuthPrompts', () => {
+  test('parses select and conditional text prompts', () => {
+    const prompts = parseAuthPrompts(copilotPrompts);
+
+    expect(prompts).toHaveLength(2);
+    expect(prompts[0]).toEqual({
+      type: 'select',
+      key: 'deploymentType',
+      message: 'Select GitHub deployment type',
+      options: [
+        { value: 'github.com', label: 'GitHub.com', hint: 'Public' },
+        { value: 'enterprise', label: 'GitHub Enterprise' },
+      ],
+    });
+    expect(prompts[1]).toEqual({
+      type: 'text',
+      key: 'enterpriseUrl',
+      message: 'Enter your GitHub Enterprise URL or domain',
+      options: [],
+      placeholder: 'company.ghe.com',
+      when: { key: 'deploymentType', op: 'eq', value: 'enterprise' },
+    });
+  });
+
+  test('returns an empty list for a method without prompts', () => {
+    expect(parseAuthPrompts(undefined)).toEqual([]);
+    expect(parseAuthPrompts(null)).toEqual([]);
+    expect(parseAuthPrompts({})).toEqual([]);
+  });
+
+  test('drops entries that could never be answered', () => {
+    const prompts = parseAuthPrompts([
+      { type: 'text', message: 'no key' },
+      { type: 'select', key: 'empty', message: 'no options', options: [] },
+      { type: 'text', key: 'keep', message: 'keep me' },
+    ]);
+
+    expect(prompts.map((prompt) => prompt.key)).toEqual(['keep']);
+  });
+
+  test('falls back to the key when a message is missing', () => {
+    expect(parseAuthPrompts([{ type: 'text', key: 'token' }])[0]?.message).toBe('token');
+  });
+
+  test('ignores a malformed when condition instead of hiding the prompt', () => {
+    const [prompt] = parseAuthPrompts([
+      { type: 'text', key: 'url', message: 'URL', when: { key: 'other', op: 'contains', value: 'x' } },
+    ]);
+
+    expect(prompt.when).toBe(undefined);
+    expect(isPromptVisible(prompt, {})).toBe(true);
+  });
+});
+
+describe('prompt visibility', () => {
+  const prompts = parseAuthPrompts(copilotPrompts);
+
+  test('hides a conditional prompt until its branch is selected', () => {
+    expect(visiblePrompts(prompts, { deploymentType: 'github.com' }).map((p) => p.key))
+      .toEqual(['deploymentType']);
+    expect(visiblePrompts(prompts, { deploymentType: 'enterprise' }).map((p) => p.key))
+      .toEqual(['deploymentType', 'enterpriseUrl']);
+  });
+
+  test('supports neq conditions', () => {
+    const prompt: AuthPrompt = {
+      type: 'text',
+      key: 'custom',
+      message: 'Custom',
+      options: [],
+      when: { key: 'mode', op: 'neq', value: 'default' },
+    };
+
+    expect(isPromptVisible(prompt, { mode: 'default' })).toBe(false);
+    expect(isPromptVisible(prompt, { mode: 'other' })).toBe(true);
+    expect(isPromptVisible(prompt, {})).toBe(true);
+  });
+});
+
+describe('prompt answers', () => {
+  const prompts = parseAuthPrompts(copilotPrompts);
+
+  test('preselects the first select option so the form starts answerable', () => {
+    expect(defaultPromptValues(prompts)).toEqual({ deploymentType: 'github.com', enterpriseUrl: '' });
+    expect(firstUnansweredPrompt(prompts, defaultPromptValues(prompts))).toBeNull();
+  });
+
+  test('reports the hidden-then-revealed field as unanswered', () => {
+    const values = { deploymentType: 'enterprise', enterpriseUrl: '   ' };
+
+    expect(firstUnansweredPrompt(prompts, values)?.key).toBe('enterpriseUrl');
+  });
+
+  test('omits answers whose prompt is no longer visible', () => {
+    const values = { deploymentType: 'github.com', enterpriseUrl: 'left-over.ghe.com' };
+
+    expect(collectPromptInputs(prompts, values)).toEqual({ deploymentType: 'github.com' });
+  });
+
+  test('trims submitted answers', () => {
+    const values = { deploymentType: 'enterprise', enterpriseUrl: '  company.ghe.com  ' };
+
+    expect(collectPromptInputs(prompts, values)).toEqual({
+      deploymentType: 'enterprise',
+      enterpriseUrl: 'company.ghe.com',
+    });
+  });
+});
+
+describe('parseAuthorization', () => {
+  test('reads a device-code authorization and recovers the code from instructions', () => {
+    const authorization = parseAuthorization({
+      url: 'https://github.com/login/device',
+      instructions: 'Enter code: 1A2B-3C4D',
+      method: 'auto',
+    });
+
+    expect(authorization).toEqual({
+      method: 'auto',
+      url: 'https://github.com/login/device',
+      instructions: 'Enter code: 1A2B-3C4D',
+      userCode: '1A2B-3C4D',
+    });
+  });
+
+  test('keeps an explicitly reported code over the instructions match', () => {
+    expect(parseAuthorization({
+      url: 'https://example.com',
+      instructions: 'Enter code: AAAA-BBBB',
+      user_code: 'ZZZZ-9999',
+      method: 'auto',
+    })?.userCode).toBe('ZZZZ-9999');
+  });
+
+  test('preserves the code method', () => {
+    expect(parseAuthorization({ url: 'https://example.com', method: 'code' })?.method).toBe('code');
+  });
+
+  test('treats a missing or unknown method as auto', () => {
+    expect(parseAuthorization({ url: 'https://example.com' })?.method).toBe('auto');
+    expect(parseAuthorization({ url: 'https://example.com', method: 'device' })?.method).toBe('auto');
+  });
+
+  test('unwraps a nested data envelope', () => {
+    expect(parseAuthorization({ data: { url: 'https://example.com', method: 'code' } })).toEqual({
+      method: 'code',
+      url: 'https://example.com',
+    });
+  });
+
+  test('accepts device-authorization field names', () => {
+    expect(parseAuthorization({
+      verification_uri_complete: 'https://example.com/activate?code=1',
+      message: 'Open the link',
+    })).toEqual({
+      method: 'auto',
+      url: 'https://example.com/activate?code=1',
+      instructions: 'Open the link',
+    });
+  });
+
+  test('returns null when nothing is actionable', () => {
+    expect(parseAuthorization(null)).toBeNull();
+    expect(parseAuthorization({})).toBeNull();
+    expect(parseAuthorization({ method: 'auto' })).toBeNull();
+  });
+});
+
+describe('describeOAuthError', () => {
+  const t: ProviderOAuthTranslator = (key) => key;
+  const fallback = 'settings.providers.page.toast.oauthCompleteFailed';
+
+  /** Names come from OpenCode's ProviderAuthApiError schema. */
+  test('maps each provider auth error name to its own message', () => {
+    expect(describeOAuthError({ name: 'ProviderAuthOauthMissing', data: {} }, t, fallback))
+      .toBe('settings.providers.page.auth.oauth.error.sessionExpired');
+    expect(describeOAuthError({ name: 'ProviderAuthOauthCodeMissing', data: {} }, t, fallback))
+      .toBe('settings.providers.page.auth.oauth.error.codeRequired');
+    expect(describeOAuthError({ name: 'ProviderAuthOauthCallbackFailed', data: {} }, t, fallback))
+      .toBe('settings.providers.page.auth.oauth.error.declined');
+  });
+
+  test('surfaces the plugin-authored validation message verbatim', () => {
+    const error = {
+      name: 'ProviderAuthValidationFailed',
+      data: { field: 'enterpriseUrl', message: 'URL or domain is required' },
+    };
+
+    expect(describeOAuthError(error, t, fallback)).toBe('URL or domain is required');
+  });
+
+  test('falls back when a validation failure carries no message', () => {
+    expect(describeOAuthError({ name: 'ProviderAuthValidationFailed', data: {} }, t, fallback))
+      .toBe('settings.providers.page.auth.oauth.error.invalidInput');
+  });
+
+  test('falls back for unknown, empty, and non-object errors', () => {
+    expect(describeOAuthError({ name: 'BadRequest', data: {} }, t, fallback)).toBe(fallback);
+    expect(describeOAuthError(new Error('network down'), t, fallback)).toBe(fallback);
+    expect(describeOAuthError(undefined, t, fallback)).toBe(fallback);
+  });
+});
diff --git a/packages/ui/src/components/sections/providers/provider-oauth.ts b/packages/ui/src/components/sections/providers/provider-oauth.ts
new file mode 100644
index 00000000..f85a8ef6
--- /dev/null
+++ b/packages/ui/src/components/sections/providers/provider-oauth.ts
@@ -0,0 +1,244 @@
+/**
+ * Provider OAuth flow helpers.
+ *
+ * `POST /provider/{id}/oauth/authorize` answers with the completion method that
+ * decides what the client has to do next:
+ *
+ * - `auto` — the client must call `oauth/callback` right away and hold that
+ *   request open. Upstream blocks inside it (device-code polling, or waiting on
+ *   a loopback redirect) until the user finishes signing in, and only then
+ *   persists the credential. Nothing is stored if the client never calls it.
+ * - `code` — the user copies a code out of the browser and hands it to
+ *   `oauth/callback`.
+ *
+ * Every auth plugin shipped with OpenCode uses `auto`; `code` stays supported
+ * for third-party auth plugins that still return it.
+ */
+
+import type { I18nKey, I18nParams } from '@/lib/i18n';
+
+export type OAuthCompletionMethod = 'auto' | 'code';
+
+export type ProviderOAuthTranslator = (key: I18nKey, params?: I18nParams) => string;
+
+export interface OAuthAuthorization {
+  method: OAuthCompletionMethod;
+  url?: string;
+  instructions?: string;
+  /** Device code surfaced separately so it can be copied on its own. */
+  userCode?: string;
+}
+
+export interface AuthPromptOption {
+  label: string;
+  value: string;
+  hint?: string;
+}
+
+export interface AuthPromptCondition {
+  key: string;
+  op: 'eq' | 'neq';
+  value: string;
+}
+
+export interface AuthPrompt {
+  type: 'text' | 'select';
+  key: string;
+  message: string;
+  placeholder?: string;
+  options: AuthPromptOption[];
+  when?: AuthPromptCondition;
+}
+
+/**
+ * Device codes are only carried inside the human-readable instructions
+ * (`Enter code: ABCD-1234`), so they are recovered by shape.
+ */
+const DEVICE_CODE_PATTERN = /[A-Z0-9]{4}-[A-Z0-9]{4,5}/;
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const asText = (value: unknown): string | undefined =>
+  typeof value === 'string' && value.length > 0 ? value : undefined;
+
+const parsePromptOptions = (value: unknown): AuthPromptOption[] => {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  const options: AuthPromptOption[] = [];
+  for (const entry of value) {
+    if (!isRecord(entry)) {
+      continue;
+    }
+    const optionValue = asText(entry.value);
+    if (optionValue === undefined) {
+      continue;
+    }
+    options.push({
+      value: optionValue,
+      label: asText(entry.label) ?? optionValue,
+      ...(asText(entry.hint) ? { hint: asText(entry.hint)! } : {}),
+    });
+  }
+  return options;
+};
+
+const parsePromptCondition = (value: unknown): AuthPromptCondition | undefined => {
+  if (!isRecord(value)) {
+    return undefined;
+  }
+  const key = asText(value.key);
+  const op = value.op === 'eq' || value.op === 'neq' ? value.op : undefined;
+  if (!key || !op || typeof value.value !== 'string') {
+    return undefined;
+  }
+  return { key, op, value: value.value };
+};
+
+/** Parses the `prompts` an auth method wants answered before `authorize`. */
+export const parseAuthPrompts = (value: unknown): AuthPrompt[] => {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  const prompts: AuthPrompt[] = [];
+  for (const entry of value) {
+    if (!isRecord(entry)) {
+      continue;
+    }
+    const key = asText(entry.key);
+    if (!key) {
+      continue;
+    }
+    const type = entry.type === 'select' ? 'select' : 'text';
+    const options = type === 'select' ? parsePromptOptions(entry.options) : [];
+    // A select with no usable option can never be answered; skipping it would
+    // silently drop a required input, so treat the whole method as unusable.
+    if (type === 'select' && options.length === 0) {
+      continue;
+    }
+    const when = parsePromptCondition(entry.when);
+    prompts.push({
+      type,
+      key,
+      message: asText(entry.message) ?? key,
+      options,
+      ...(asText(entry.placeholder) ? { placeholder: asText(entry.placeholder)! } : {}),
+      ...(when ? { when } : {}),
+    });
+  }
+  return prompts;
+};
+
+/** True when a prompt's `when` condition is satisfied by the answers so far. */
+export const isPromptVisible = (prompt: AuthPrompt, values: Record<string, string>): boolean => {
+  if (!prompt.when) {
+    return true;
+  }
+  const current = values[prompt.when.key] ?? '';
+  return prompt.when.op === 'eq'
+    ? current === prompt.when.value
+    : current !== prompt.when.value;
+};
+
+export const visiblePrompts = (
+  prompts: AuthPrompt[],
+  values: Record<string, string>,
+): AuthPrompt[] => prompts.filter((prompt) => isPromptVisible(prompt, values));
+
+/** Selects preselect their first option so the form always starts answerable. */
+export const defaultPromptValues = (prompts: AuthPrompt[]): Record<string, string> => {
+  const values: Record<string, string> = {};
+  for (const prompt of prompts) {
+    values[prompt.key] = prompt.type === 'select' ? (prompt.options[0]?.value ?? '') : '';
+  }
+  return values;
+};
+
+/** First visible prompt still left blank, or `null` when the form is complete. */
+export const firstUnansweredPrompt = (
+  prompts: AuthPrompt[],
+  values: Record<string, string>,
+): AuthPrompt | null =>
+  visiblePrompts(prompts, values).find((prompt) => (values[prompt.key] ?? '').trim().length === 0) ?? null;
+
+/**
+ * Builds the `inputs` payload for `authorize`. Hidden prompts are dropped so a
+ * stale answer from a since-changed branch is never sent upstream.
+ */
+export const collectPromptInputs = (
+  prompts: AuthPrompt[],
+  values: Record<string, string>,
+): Record<string, string> => {
+  const inputs: Record<string, string> = {};
+  for (const prompt of visiblePrompts(prompts, values)) {
+    inputs[prompt.key] = (values[prompt.key] ?? '').trim();
+  }
+  return inputs;
+};
+
+/**
+ * Normalizes an `authorize` response.
+ *
+ * Anything that is not explicitly `code` is treated as `auto`: `auto` only
+ * means "call back and wait", which is also the safe reading of an unknown
+ * method, whereas guessing `code` would strand the user at a paste field no
+ * provider can fill.
+ *
+ * Returns `null` when the response carries nothing the user can act on.
+ */
+export const parseAuthorization = (payload: unknown): OAuthAuthorization | null => {
+  const outer: Record<string, unknown> = isRecord(payload) ? payload : {};
+  const record: Record<string, unknown> = isRecord(outer.data) ? outer.data : outer;
+
+  const url =
+    asText(record.url)
+    ?? asText(record.verification_uri_complete)
+    ?? asText(record.verification_uri);
+  const instructions = asText(record.instructions) ?? asText(record.message);
+
+  if (!url && !instructions) {
+    return null;
+  }
+
+  const userCode =
+    asText(record.user_code)
+    ?? asText(record.userCode)
+    ?? (instructions ? DEVICE_CODE_PATTERN.exec(instructions)?.[0] : undefined);
+
+  return {
+    method: record.method === 'code' ? 'code' : 'auto',
+    ...(url ? { url } : {}),
+    ...(instructions ? { instructions } : {}),
+    ...(userCode ? { userCode } : {}),
+  };
+};
+
+/**
+ * Renders a `ProviderAuthApiError` as user-facing copy.
+ *
+ * Validation failures carry a message authored by the auth plugin (a field
+ * rule such as "URL or domain is required"); it is shown verbatim because only
+ * the plugin knows which input was rejected.
+ */
+export const describeOAuthError = (
+  error: unknown,
+  t: ProviderOAuthTranslator,
+  fallbackKey: I18nKey,
+): string => {
+  const record: Record<string, unknown> = isRecord(error) ? error : {};
+  const data: Record<string, unknown> = isRecord(record.data) ? record.data : {};
+
+  switch (record.name) {
+    case 'ProviderAuthOauthMissing':
+      return t('settings.providers.page.auth.oauth.error.sessionExpired');
+    case 'ProviderAuthOauthCodeMissing':
+      return t('settings.providers.page.auth.oauth.error.codeRequired');
+    case 'ProviderAuthOauthCallbackFailed':
+      return t('settings.providers.page.auth.oauth.error.declined');
+    case 'ProviderAuthValidationFailed':
+      return asText(data.message) ?? t('settings.providers.page.auth.oauth.error.invalidInput');
+    default:
+      return t(fallbackKey);
+  }
+};
diff --git a/packages/ui/src/components/sections/providers/providerAuth.ts b/packages/ui/src/components/sections/providers/providerAuth.ts
index 5d253e0b..18ca4a9c 100644
--- a/packages/ui/src/components/sections/providers/providerAuth.ts
+++ b/packages/ui/src/components/sections/providers/providerAuth.ts
@@ -5,6 +5,8 @@ export interface AuthMethod {
   description?: string;
   help?: string;
   method?: number;
+  /** Inputs an OAuth method wants answered before authorize; see `provider-oauth.ts`. */
+  prompts?: unknown;
   [key: string]: unknown;
 }
 
diff --git a/packages/ui/src/lib/i18n/messages/de.settings.ts b/packages/ui/src/lib/i18n/messages/de.settings.ts
index fc3cfa86..94cc8694 100644
--- a/packages/ui/src/lib/i18n/messages/de.settings.ts
+++ b/packages/ui/src/lib/i18n/messages/de.settings.ts
@@ -1321,6 +1321,17 @@ export const settingsDict = {
   'settings.providers.page.auth.apiKeyPlaceholder': 'sk-...',
   'settings.providers.page.auth.oauthMethodFallback': 'OAuth-Methode {index}',
   'settings.providers.page.auth.pasteAuthorizationCodePlaceholder': 'Autorisierungscode einfügen',
+  'settings.providers.page.auth.oauth.starting': 'Autorisierung wird gestartet …',
+  'settings.providers.page.auth.oauth.waiting': 'Warten auf Autorisierung …',
+  'settings.providers.page.auth.oauth.waitingHint': 'Schließen Sie die Anmeldung im Browser ab. Lassen Sie diese Seite geöffnet – die Verbindung wird von selbst hergestellt.',
+  'settings.providers.page.auth.oauth.codeHint': 'Kopieren Sie den Autorisierungscode aus dem Browser und fügen Sie ihn hier ein.',
+  'settings.providers.page.auth.oauth.deviceCodeLabel': 'Gerätecode',
+  'settings.providers.page.auth.oauth.linkLabel': 'Autorisierungslink',
+  'settings.providers.page.auth.oauth.promptRequired': 'Füllen Sie „{field}“ aus, um fortzufahren',
+  'settings.providers.page.auth.oauth.error.sessionExpired': 'Die Autorisierungsanfrage ist abgelaufen. Verbinden Sie erneut, um sie neu zu starten.',
+  'settings.providers.page.auth.oauth.error.codeRequired': 'Dieser Anbieter benötigt den Autorisierungscode aus Ihrem Browser.',
+  'settings.providers.page.auth.oauth.error.declined': 'Die Autorisierung wurde abgelehnt oder nicht abgeschlossen.',
+  'settings.providers.page.auth.oauth.error.invalidInput': 'Die eingegebenen Angaben wurden abgelehnt.',
   'settings.providers.page.auth.connected': 'Verbunden',
   'settings.providers.page.auth.incomplete': 'Anmeldedaten fehlen',
   'settings.providers.page.auth.incompleteHint': '· Fügen Sie einen API-Schlüssel oder {env:VAR} hinzu, bevor Sie diesen Anbieter im Chat verwenden',
@@ -1351,6 +1362,9 @@ export const settingsDict = {
   'settings.providers.page.actions.open': 'Öffnen',
   'settings.providers.page.actions.copy': 'Kopieren',
   'settings.providers.page.actions.complete': 'Vervollständigen',
+  'settings.providers.page.actions.continue': 'Weiter',
+  'settings.providers.page.actions.cancel': 'Abbrechen',
+  'settings.providers.page.actions.tryAgain': 'Wiederholen',
   'settings.providers.page.actions.hide': 'Ausblenden',
   'settings.providers.page.actions.reconnect': 'Erneut verbinden',
   'settings.providers.page.actions.edit': 'Bearbeiten',
@@ -1365,7 +1379,6 @@ export const settingsDict = {
   'settings.providers.page.toast.apiKeySaved': 'API-Schlüssel gespeichert',
   'settings.providers.page.toast.oauthStartFailed': 'Fehler beim Starten des OAuth-Flows',
   'settings.providers.page.toast.oauthDetailsMissing': 'Keine OAuth-Details zurückgegeben',
-  'settings.providers.page.toast.completeOAuthInBrowser': 'Schließen Sie den OAuth-Flow in Ihrem Browser ab',
   'settings.providers.page.toast.oauthCompleteFailed': 'Fehler beim Abschließen des OAuth-Flows',
   'settings.providers.page.toast.oauthCompleted': 'OAuth-Verbindung abgeschlossen',
   'settings.providers.page.toast.oauthLinkCopied': 'OAuth-Link kopiert',
diff --git a/packages/ui/src/lib/i18n/messages/en.settings.ts b/packages/ui/src/lib/i18n/messages/en.settings.ts
index 4a1deb81..82ef3778 100644
--- a/packages/ui/src/lib/i18n/messages/en.settings.ts
+++ b/packages/ui/src/lib/i18n/messages/en.settings.ts
@@ -1386,6 +1386,17 @@ export const settingsDict = {
   'settings.providers.page.auth.apiKeyPlaceholder': 'sk-...',
   'settings.providers.page.auth.oauthMethodFallback': 'OAuth method {index}',
   'settings.providers.page.auth.pasteAuthorizationCodePlaceholder': 'Paste authorization code',
+  'settings.providers.page.auth.oauth.starting': 'Starting authorization…',
+  'settings.providers.page.auth.oauth.waiting': 'Waiting for authorization…',
+  'settings.providers.page.auth.oauth.waitingHint': 'Finish signing in in your browser. Keep this page open — the connection completes on its own.',
+  'settings.providers.page.auth.oauth.codeHint': 'Copy the authorization code from your browser and paste it here.',
+  'settings.providers.page.auth.oauth.deviceCodeLabel': 'Device code',
+  'settings.providers.page.auth.oauth.linkLabel': 'Authorization link',
+  'settings.providers.page.auth.oauth.promptRequired': 'Fill in “{field}” to continue',
+  'settings.providers.page.auth.oauth.error.sessionExpired': 'The authorization request expired. Connect again to restart it.',
+  'settings.providers.page.auth.oauth.error.codeRequired': 'This provider needs the authorization code from your browser.',
+  'settings.providers.page.auth.oauth.error.declined': 'Authorization was declined or did not complete.',
+  'settings.providers.page.auth.oauth.error.invalidInput': 'The details you entered were rejected.',
   'settings.providers.page.auth.connected': 'Connected',
   'settings.providers.page.auth.incomplete': 'Credentials missing',
   'settings.providers.page.auth.incompleteHint': '· Add an API key or {env:VAR} before using this provider in chat',
@@ -1416,6 +1427,9 @@ export const settingsDict = {
   'settings.providers.page.actions.open': 'Open',
   'settings.providers.page.actions.copy': 'Copy',
   'settings.providers.page.actions.complete': 'Complete',
+  'settings.providers.page.actions.continue': 'Continue',
+  'settings.providers.page.actions.cancel': 'Cancel',
+  'settings.providers.page.actions.tryAgain': 'Try again',
   'settings.providers.page.actions.hide': 'Hide',
   'settings.providers.page.actions.reconnect': 'Reconnect',
   'settings.providers.page.actions.edit': 'Edit',
@@ -1430,7 +1444,6 @@ export const settingsDict = {
   'settings.providers.page.toast.apiKeySaved': 'API key saved',
   'settings.providers.page.toast.oauthStartFailed': 'Failed to start OAuth flow',
   'settings.providers.page.toast.oauthDetailsMissing': 'No OAuth details returned',
-  'settings.providers.page.toast.completeOAuthInBrowser': 'Complete the OAuth flow in your browser',
   'settings.providers.page.toast.oauthCompleteFailed': 'Failed to complete OAuth flow',
   'settings.providers.page.toast.oauthCompleted': 'OAuth connection completed',
   'settings.providers.page.toast.oauthLinkCopied': 'OAuth link copied',
diff --git a/packages/ui/src/lib/i18n/messages/es.settings.ts b/packages/ui/src/lib/i18n/messages/es.settings.ts
index 31b07208..b4613162 100644
--- a/packages/ui/src/lib/i18n/messages/es.settings.ts
+++ b/packages/ui/src/lib/i18n/messages/es.settings.ts
@@ -1359,6 +1359,17 @@ export const settingsDict = {
   "settings.providers.page.auth.apiKeyPlaceholder": "sk-...",
   "settings.providers.page.auth.oauthMethodFallback": "Método OAuth {index}",
   "settings.providers.page.auth.pasteAuthorizationCodePlaceholder": "Pegar código de autorización",
+  "settings.providers.page.auth.oauth.starting": "Iniciando la autorización…",
+  "settings.providers.page.auth.oauth.waiting": "Esperando la autorización…",
+  "settings.providers.page.auth.oauth.waitingHint": "Termina de iniciar sesión en el navegador. Mantén esta página abierta: la conexión se completará sola.",
+  "settings.providers.page.auth.oauth.codeHint": "Copia el código de autorización del navegador y pégalo aquí.",
+  "settings.providers.page.auth.oauth.deviceCodeLabel": "Código del dispositivo",
+  "settings.providers.page.auth.oauth.linkLabel": "Enlace de autorización",
+  "settings.providers.page.auth.oauth.promptRequired": "Completa «{field}» para continuar",
+  "settings.providers.page.auth.oauth.error.sessionExpired": "La solicitud de autorización caducó. Vuelve a conectar para reiniciarla.",
+  "settings.providers.page.auth.oauth.error.codeRequired": "Este proveedor necesita el código de autorización de tu navegador.",
+  "settings.providers.page.auth.oauth.error.declined": "La autorización se rechazó o no se completó.",
+  "settings.providers.page.auth.oauth.error.invalidInput": "Se rechazaron los datos introducidos.",
   "settings.providers.page.auth.connected": "Conectado",
   "settings.providers.page.auth.incomplete": "Faltan credenciales",
   "settings.providers.page.auth.incompleteHint": "· Añade una clave API o {env:VAR} antes de usar este proveedor en el chat",
@@ -1391,6 +1402,9 @@ export const settingsDict = {
   "settings.providers.page.actions.open": "Abrir",
   "settings.providers.page.actions.copy": "Copiar",
   "settings.providers.page.actions.complete": "Completar",
+  "settings.providers.page.actions.continue": "Continuar",
+  "settings.providers.page.actions.cancel": "Cancelar",
+  "settings.providers.page.actions.tryAgain": "Reintentar",
   "settings.providers.page.actions.hide": "Ocultar",
   "settings.providers.page.actions.reconnect": "Reconectar",
   "settings.providers.page.actions.edit": "Editar",
@@ -1406,7 +1420,6 @@ export const settingsDict = {
   "settings.providers.page.toast.apiKeySaved": "Clave API guardada",
   "settings.providers.page.toast.oauthStartFailed": "No se pudo iniciar el flujo OAuth",
   "settings.providers.page.toast.oauthDetailsMissing": "No se devolvieron detalles de OAuth",
-  "settings.providers.page.toast.completeOAuthInBrowser": "Completa el flujo OAuth en tu navegador",
   "settings.providers.page.toast.oauthCompleteFailed": "No se pudo completar el flujo OAuth",
   "settings.providers.page.toast.oauthCompleted": "Conexión OAuth completada",
   "settings.providers.page.toast.oauthLinkCopied": "Enlace de OAuth copiado",
diff --git a/packages/ui/src/lib/i18n/messages/fr.settings.ts b/packages/ui/src/lib/i18n/messages/fr.settings.ts
index f5dc26d4..249dfad8 100644
--- a/packages/ui/src/lib/i18n/messages/fr.settings.ts
+++ b/packages/ui/src/lib/i18n/messages/fr.settings.ts
@@ -1280,6 +1280,17 @@ export const settingsDict = {
   'settings.providers.page.auth.apiKeyPlaceholder': 'sk-...',
   'settings.providers.page.auth.oauthMethodFallback': 'Méthode OAuth {index}',
   'settings.providers.page.auth.pasteAuthorizationCodePlaceholder': 'Coller le code d\'autorisation',
+  'settings.providers.page.auth.oauth.starting': 'Démarrage de l’autorisation…',
+  'settings.providers.page.auth.oauth.waiting': 'En attente de l’autorisation…',
+  'settings.providers.page.auth.oauth.waitingHint': 'Terminez la connexion dans votre navigateur. Laissez cette page ouverte : la connexion se finalisera d’elle-même.',
+  'settings.providers.page.auth.oauth.codeHint': 'Copiez le code d’autorisation depuis votre navigateur et collez-le ici.',
+  'settings.providers.page.auth.oauth.deviceCodeLabel': 'Code de l’appareil',
+  'settings.providers.page.auth.oauth.linkLabel': 'Lien d’autorisation',
+  'settings.providers.page.auth.oauth.promptRequired': 'Renseignez « {field} » pour continuer',
+  'settings.providers.page.auth.oauth.error.sessionExpired': 'La demande d’autorisation a expiré. Reconnectez-vous pour la relancer.',
+  'settings.providers.page.auth.oauth.error.codeRequired': 'Ce fournisseur a besoin du code d’autorisation de votre navigateur.',
+  'settings.providers.page.auth.oauth.error.declined': 'L’autorisation a été refusée ou n’a pas abouti.',
+  'settings.providers.page.auth.oauth.error.invalidInput': 'Les informations saisies ont été refusées.',
   'settings.providers.page.auth.connected': 'Connecté',
   'settings.providers.page.auth.incomplete': 'Identifiants manquants',
   'settings.providers.page.auth.incompleteHint': '· Ajoutez une clé API ou {env:VAR} avant d’utiliser ce fournisseur dans le chat',
@@ -1312,6 +1323,9 @@ export const settingsDict = {
   'settings.providers.page.actions.open': 'Ouvrir',
   'settings.providers.page.actions.copy': 'Copie',
   'settings.providers.page.actions.complete': 'Complet',
+  'settings.providers.page.actions.continue': 'Continuer',
+  'settings.providers.page.actions.cancel': 'Annuler',
+  'settings.providers.page.actions.tryAgain': 'Réessayer',
   'settings.providers.page.actions.hide': 'Cacher',
   'settings.providers.page.actions.reconnect': 'Reconnecter',
   'settings.providers.page.actions.edit': 'Modifier',
@@ -1327,7 +1341,6 @@ export const settingsDict = {
   'settings.providers.page.toast.apiKeySaved': 'Clé API enregistrée',
   'settings.providers.page.toast.oauthStartFailed': 'Échec du démarrage du flux OAuth',
   'settings.providers.page.toast.oauthDetailsMissing': 'Aucun détail OAuth renvoyé',
-  'settings.providers.page.toast.completeOAuthInBrowser': 'Complétez le flux OAuth dans votre navigateur',
   'settings.providers.page.toast.oauthCompleteFailed': 'Échec de la réalisation du flux OAuth',
   'settings.providers.page.toast.oauthCompleted': 'Connexion OAuth terminée',
   'settings.providers.page.toast.oauthLinkCopied': 'Lien OAuth copié',
diff --git a/packages/ui/src/lib/i18n/messages/ja.settings.ts b/packages/ui/src/lib/i18n/messages/ja.settings.ts
index 3d7565a9..f2c58bdd 100644
--- a/packages/ui/src/lib/i18n/messages/ja.settings.ts
+++ b/packages/ui/src/lib/i18n/messages/ja.settings.ts
@@ -1392,6 +1392,17 @@ export const settingsDict = {
   'settings.providers.page.auth.apiKeyPlaceholder': 'sk-...',
   'settings.providers.page.auth.oauthMethodFallback': 'OAuth 方法 {index}',
   'settings.providers.page.auth.pasteAuthorizationCodePlaceholder': '認証コードを貼り付け',
+  'settings.providers.page.auth.oauth.starting': '認証を開始しています…',
+  'settings.providers.page.auth.oauth.waiting': '認証を待っています…',
+  'settings.providers.page.auth.oauth.waitingHint': 'ブラウザーでサインインを完了してください。このページは開いたままにしてください。接続は自動的に完了します。',
+  'settings.providers.page.auth.oauth.codeHint': 'ブラウザーから認証コードをコピーして、ここに貼り付けてください。',
+  'settings.providers.page.auth.oauth.deviceCodeLabel': 'デバイスコード',
+  'settings.providers.page.auth.oauth.linkLabel': '認証リンク',
+  'settings.providers.page.auth.oauth.promptRequired': '続行するには「{field}」を入力してください',
+  'settings.providers.page.auth.oauth.error.sessionExpired': '認証リクエストの有効期限が切れました。もう一度接続してやり直してください。',
+  'settings.providers.page.auth.oauth.error.codeRequired': 'このプロバイダーにはブラウザーの認証コードが必要です。',
+  'settings.providers.page.auth.oauth.error.declined': '認証が拒否されたか、完了しませんでした。',
+  'settings.providers.page.auth.oauth.error.invalidInput': '入力された内容は拒否されました。',
   'settings.providers.page.auth.connected': '接続済み',
   'settings.providers.page.auth.incomplete': '認証情報が不足しています',
   'settings.providers.page.auth.incompleteHint': '· チャットでこのプロバイダーを使う前に API キーまたは {env:VAR} を追加してください',
@@ -1424,6 +1435,9 @@ export const settingsDict = {
   'settings.providers.page.actions.open': '開く',
   'settings.providers.page.actions.copy': 'コピー',
   'settings.providers.page.actions.complete': '完了',
+  'settings.providers.page.actions.continue': '続行',
+  'settings.providers.page.actions.cancel': 'キャンセル',
+  'settings.providers.page.actions.tryAgain': '再試行',
   'settings.providers.page.actions.hide': '非表示',
   'settings.providers.page.actions.reconnect': '再接続',
   'settings.providers.page.actions.edit': '編集',
@@ -1439,7 +1453,6 @@ export const settingsDict = {
   'settings.providers.page.toast.apiKeySaved': 'API キーを保存しました',
   'settings.providers.page.toast.oauthStartFailed': 'OAuth フローの開始に失敗しました',
   'settings.providers.page.toast.oauthDetailsMissing': 'OAuth の詳細が返されませんでした',
-  'settings.providers.page.toast.completeOAuthInBrowser': 'ブラウザで OAuth フローを完了してください',
   'settings.providers.page.toast.oauthCompleteFailed': 'OAuth フローの完了に失敗しました',
   'settings.providers.page.toast.oauthCompleted': 'OAuth 接続が完了しました',
   'settings.providers.page.toast.oauthLinkCopied': 'OAuth リンクをコピーしました',
diff --git a/packages/ui/src/lib/i18n/messages/ko.settings.ts b/packages/ui/src/lib/i18n/messages/ko.settings.ts
index df181c60..0f9b0aba 100644
--- a/packages/ui/src/lib/i18n/messages/ko.settings.ts
+++ b/packages/ui/src/lib/i18n/messages/ko.settings.ts
@@ -1359,6 +1359,17 @@ export const settingsDict = {
   'settings.providers.page.auth.apiKeyPlaceholder': 'sk-...',
   'settings.providers.page.auth.oauthMethodFallback': 'OAuth 방식 {index}',
   'settings.providers.page.auth.pasteAuthorizationCodePlaceholder': 'authorization code 붙여넣기',
+  'settings.providers.page.auth.oauth.starting': '인증을 시작하는 중…',
+  'settings.providers.page.auth.oauth.waiting': '인증을 기다리는 중…',
+  'settings.providers.page.auth.oauth.waitingHint': '브라우저에서 로그인을 완료하세요. 이 페이지를 열어 두면 연결이 자동으로 완료됩니다.',
+  'settings.providers.page.auth.oauth.codeHint': '브라우저에서 인증 코드를 복사해 여기에 붙여넣으세요.',
+  'settings.providers.page.auth.oauth.deviceCodeLabel': '기기 코드',
+  'settings.providers.page.auth.oauth.linkLabel': '인증 링크',
+  'settings.providers.page.auth.oauth.promptRequired': '계속하려면 “{field}”을(를) 입력하세요',
+  'settings.providers.page.auth.oauth.error.sessionExpired': '인증 요청이 만료되었습니다. 다시 연결해 처음부터 시작하세요.',
+  'settings.providers.page.auth.oauth.error.codeRequired': '이 제공자에는 브라우저의 인증 코드가 필요합니다.',
+  'settings.providers.page.auth.oauth.error.declined': '인증이 거부되었거나 완료되지 않았습니다.',
+  'settings.providers.page.auth.oauth.error.invalidInput': '입력한 정보가 거부되었습니다.',
   'settings.providers.page.auth.connected': '연결됨',
   'settings.providers.page.auth.incomplete': '자격 증명 없음',
   'settings.providers.page.auth.incompleteHint': '· 채팅에서 이 공급자를 사용하기 전에 API 키 또는 {env:VAR}을(를) 추가하세요',
@@ -1391,6 +1402,9 @@ export const settingsDict = {
   'settings.providers.page.actions.open': '열기',
   'settings.providers.page.actions.copy': '복사',
   'settings.providers.page.actions.complete': '완료',
+  'settings.providers.page.actions.continue': '계속',
+  'settings.providers.page.actions.cancel': '취소',
+  'settings.providers.page.actions.tryAgain': '다시 시도',
   'settings.providers.page.actions.hide': '숨기기',
   'settings.providers.page.actions.reconnect': '재연결',
   'settings.providers.page.actions.edit': '편집',
@@ -1406,7 +1420,6 @@ export const settingsDict = {
   'settings.providers.page.toast.apiKeySaved': 'API key가 저장되었습니다',
   'settings.providers.page.toast.oauthStartFailed': 'OAuth flow를 시작하지 못했습니다',
   'settings.providers.page.toast.oauthDetailsMissing': '반환된 OAuth 세부 정보가 없습니다',
-  'settings.providers.page.toast.completeOAuthInBrowser': '브라우저에서 OAuth flow를 완료하세요',
   'settings.providers.page.toast.oauthCompleteFailed': 'OAuth flow를 완료하지 못했습니다',
   'settings.providers.page.toast.oauthCompleted': 'OAuth 연결이 완료되었습니다',
   'settings.providers.page.toast.oauthLinkCopied': 'OAuth 링크가 복사되었습니다',
diff --git a/packages/ui/src/lib/i18n/messages/pl.settings.ts b/packages/ui/src/lib/i18n/messages/pl.settings.ts
index dcc3d774..89bafd5b 100644
--- a/packages/ui/src/lib/i18n/messages/pl.settings.ts
+++ b/packages/ui/src/lib/i18n/messages/pl.settings.ts
@@ -1360,6 +1360,9 @@ export const settingsDict = {
   'settings.projects.sidebar.actions.addProject': 'Dodaj projekt',
   'settings.projects.sidebar.total': 'Suma: {count}',
   'settings.providers.page.actions.complete': 'Zakończ',
+  'settings.providers.page.actions.continue': 'Kontynuuj',
+  'settings.providers.page.actions.cancel': 'Anuluj',
+  'settings.providers.page.actions.tryAgain': 'Spróbuj ponownie',
   'settings.providers.page.actions.connect': 'Połącz',
   'settings.providers.page.actions.copy': 'Kopiuj',
   'settings.providers.page.actions.copyCode': 'Kopiuj kod',
@@ -1385,6 +1388,17 @@ export const settingsDict = {
   'settings.providers.page.auth.loadingMethods': 'Ładowanie metod uwierzytelniania...',
   'settings.providers.page.auth.oauthMethodFallback': 'Metoda OAuth {index}',
   'settings.providers.page.auth.pasteAuthorizationCodePlaceholder': 'Wklej kod autoryzacyjny',
+  'settings.providers.page.auth.oauth.starting': 'Rozpoczynanie autoryzacji…',
+  'settings.providers.page.auth.oauth.waiting': 'Oczekiwanie na autoryzację…',
+  'settings.providers.page.auth.oauth.waitingHint': 'Dokończ logowanie w przeglądarce. Zostaw tę stronę otwartą — połączenie zakończy się samo.',
+  'settings.providers.page.auth.oauth.codeHint': 'Skopiuj kod autoryzacji z przeglądarki i wklej go tutaj.',
+  'settings.providers.page.auth.oauth.deviceCodeLabel': 'Kod urządzenia',
+  'settings.providers.page.auth.oauth.linkLabel': 'Link autoryzacyjny',
+  'settings.providers.page.auth.oauth.promptRequired': 'Wypełnij pole „{field}”, aby kontynuować',
+  'settings.providers.page.auth.oauth.error.sessionExpired': 'Żądanie autoryzacji wygasło. Połącz ponownie, aby zacząć od nowa.',
+  'settings.providers.page.auth.oauth.error.codeRequired': 'Ten dostawca wymaga kodu autoryzacji z przeglądarki.',
+  'settings.providers.page.auth.oauth.error.declined': 'Autoryzacja została odrzucona lub nie została ukończona.',
+  'settings.providers.page.auth.oauth.error.invalidInput': 'Wprowadzone dane zostały odrzucone.',
   'settings.providers.page.auth.title': 'Uwierzytelnianie',
   'settings.providers.page.auth.useReconnectHint': '· Użyj Połącz ponownie, aby zaktualizować dane logowania',
   'settings.providers.page.custom.optionLabel': 'Inny / Niestandardowy',
@@ -1474,7 +1488,6 @@ export const settingsDict = {
   'settings.providers.page.toast.apiKeySaveFailed': 'Nie udało się zapisać klucza API',
   'settings.providers.page.toast.apiKeySaved': 'Klucz API został zapisany',
   'settings.providers.page.toast.authMethodsLoadFailed': 'Nie udało się załadować metod uwierzytelniania dostawcy',
-  'settings.providers.page.toast.completeOAuthInBrowser': 'Dokończ proces OAuth w przeglądarce',
   'settings.providers.page.toast.deviceCodeCopied': 'Kod urządzenia został skopiowany',
   'settings.providers.page.toast.deviceCodeCopyFailed': 'Nie udało się skopiować kodu urządzenia',
   'settings.providers.page.toast.oauthCompleteFailed': 'Nie udało się dokończyć procesu OAuth',
diff --git a/packages/ui/src/lib/i18n/messages/pt-BR.settings.ts b/packages/ui/src/lib/i18n/messages/pt-BR.settings.ts
index 5950ec10..73386454 100644
--- a/packages/ui/src/lib/i18n/messages/pt-BR.settings.ts
+++ b/packages/ui/src/lib/i18n/messages/pt-BR.settings.ts
@@ -1359,6 +1359,17 @@ export const settingsDict = {
   "settings.providers.page.auth.apiKeyPlaceholder": "sk-...",
   "settings.providers.page.auth.oauthMethodFallback": "Método OAuth {index}",
   "settings.providers.page.auth.pasteAuthorizationCodePlaceholder": "Colar código de autorização",
+  "settings.providers.page.auth.oauth.starting": "Iniciando a autorização…",
+  "settings.providers.page.auth.oauth.waiting": "Aguardando a autorização…",
+  "settings.providers.page.auth.oauth.waitingHint": "Conclua o login no navegador. Mantenha esta página aberta — a conexão será concluída sozinha.",
+  "settings.providers.page.auth.oauth.codeHint": "Copie o código de autorização do navegador e cole aqui.",
+  "settings.providers.page.auth.oauth.deviceCodeLabel": "Código do dispositivo",
+  "settings.providers.page.auth.oauth.linkLabel": "Link de autorização",
+  "settings.providers.page.auth.oauth.promptRequired": "Preencha “{field}” para continuar",
+  "settings.providers.page.auth.oauth.error.sessionExpired": "A solicitação de autorização expirou. Conecte novamente para reiniciá-la.",
+  "settings.providers.page.auth.oauth.error.codeRequired": "Este provedor precisa do código de autorização do seu navegador.",
+  "settings.providers.page.auth.oauth.error.declined": "A autorização foi recusada ou não foi concluída.",
+  "settings.providers.page.auth.oauth.error.invalidInput": "Os dados informados foram recusados.",
   "settings.providers.page.auth.connected": "Conectado",
   "settings.providers.page.auth.incomplete": "Credenciais ausentes",
   "settings.providers.page.auth.incompleteHint": "· Adicione uma chave de API ou {env:VAR} antes de usar este provedor no chat",
@@ -1391,6 +1402,9 @@ export const settingsDict = {
   "settings.providers.page.actions.open": "Abrir",
   "settings.providers.page.actions.copy": "Copiar",
   "settings.providers.page.actions.complete": "Completar",
+  "settings.providers.page.actions.continue": "Continuar",
+  "settings.providers.page.actions.cancel": "Cancelar",
+  "settings.providers.page.actions.tryAgain": "Tentar novamente",
   "settings.providers.page.actions.hide": "Ocultar",
   "settings.providers.page.actions.reconnect": "Reconectar",
   "settings.providers.page.actions.edit": "Editar",
@@ -1406,7 +1420,6 @@ export const settingsDict = {
   "settings.providers.page.toast.apiKeySaved": "Chave API salva",
   "settings.providers.page.toast.oauthStartFailed": "Não foi possível iniciar o fluxo OAuth",
   "settings.providers.page.toast.oauthDetailsMissing": "Não se devolvieron detalhes de OAuth",
-  "settings.providers.page.toast.completeOAuthInBrowser": "Complete o fluxo OAuth no navegador",
   "settings.providers.page.toast.oauthCompleteFailed": "Não foi possível concluir o fluxo OAuth",
   "settings.providers.page.toast.oauthCompleted": "Conexão OAuth concluída",
   "settings.providers.page.toast.oauthLinkCopied": "Link de OAuth copiado",
diff --git a/packages/ui/src/lib/i18n/messages/uk.settings.ts b/packages/ui/src/lib/i18n/messages/uk.settings.ts
index 306608d2..42d29d22 100644
--- a/packages/ui/src/lib/i18n/messages/uk.settings.ts
+++ b/packages/ui/src/lib/i18n/messages/uk.settings.ts
@@ -1359,6 +1359,17 @@ export const settingsDict = {
   "settings.providers.page.auth.apiKeyPlaceholder": "sk-...",
   "settings.providers.page.auth.oauthMethodFallback": "OAuth метод {index}",
   "settings.providers.page.auth.pasteAuthorizationCodePlaceholder": "Вставити код авторизації",
+  "settings.providers.page.auth.oauth.starting": "Запускаємо авторизацію…",
+  "settings.providers.page.auth.oauth.waiting": "Очікуємо на авторизацію…",
+  "settings.providers.page.auth.oauth.waitingHint": "Завершіть вхід у браузері. Не закривайте цю сторінку — підключення завершиться саме.",
+  "settings.providers.page.auth.oauth.codeHint": "Скопіюйте код авторизації з браузера і вставте його сюди.",
+  "settings.providers.page.auth.oauth.deviceCodeLabel": "Код пристрою",
+  "settings.providers.page.auth.oauth.linkLabel": "Посилання для авторизації",
+  "settings.providers.page.auth.oauth.promptRequired": "Заповніть «{field}», щоб продовжити",
+  "settings.providers.page.auth.oauth.error.sessionExpired": "Термін дії запиту на авторизацію минув. Підключіться ще раз, щоб почати заново.",
+  "settings.providers.page.auth.oauth.error.codeRequired": "Цьому провайдеру потрібен код авторизації з браузера.",
+  "settings.providers.page.auth.oauth.error.declined": "Авторизацію відхилено або не завершено.",
+  "settings.providers.page.auth.oauth.error.invalidInput": "Введені дані відхилено.",
   "settings.providers.page.auth.connected": "Підключено",
   "settings.providers.page.auth.incomplete": "Облікові дані відсутні",
   "settings.providers.page.auth.incompleteHint": "· Додайте API-ключ або {env:VAR} перед використанням цього провайдера в чаті",
@@ -1391,6 +1402,9 @@ export const settingsDict = {
   "settings.providers.page.actions.open": "Відкрити",
   "settings.providers.page.actions.copy": "Копіювати",
   "settings.providers.page.actions.complete": "Завершити",
+  "settings.providers.page.actions.continue": "Продовжити",
+  "settings.providers.page.actions.cancel": "Скасувати",
+  "settings.providers.page.actions.tryAgain": "Повторити спробу",
   "settings.providers.page.actions.hide": "Сховати",
   "settings.providers.page.actions.reconnect": "Перепідключити",
   "settings.providers.page.actions.edit": "Редагувати",
@@ -1406,7 +1420,6 @@ export const settingsDict = {
   "settings.providers.page.toast.apiKeySaved": "Ключ API збережено",
   "settings.providers.page.toast.oauthStartFailed": "Не вдалося запустити потік OAuth",
   "settings.providers.page.toast.oauthDetailsMissing": "Деталі OAuth не повернуто",
-  "settings.providers.page.toast.completeOAuthInBrowser": "Завершіть процес OAuth у вашому браузері",
   "settings.providers.page.toast.oauthCompleteFailed": "Не вдалося завершити потік OAuth",
   "settings.providers.page.toast.oauthCompleted": "Підключення OAuth завершено",
   "settings.providers.page.toast.oauthLinkCopied": "Посилання OAuth скопійовано",
diff --git a/packages/ui/src/lib/i18n/messages/zh-CN.settings.ts b/packages/ui/src/lib/i18n/messages/zh-CN.settings.ts
index 42aa7d0a..36f85a43 100644
--- a/packages/ui/src/lib/i18n/messages/zh-CN.settings.ts
+++ b/packages/ui/src/lib/i18n/messages/zh-CN.settings.ts
@@ -1359,6 +1359,17 @@ export const settingsDict = {
   'settings.providers.page.auth.apiKeyPlaceholder': 'sk-...',
   'settings.providers.page.auth.oauthMethodFallback': 'OAuth 方式 {index}',
   'settings.providers.page.auth.pasteAuthorizationCodePlaceholder': '粘贴授权码',
+  'settings.providers.page.auth.oauth.starting': '正在启动授权…',
+  'settings.providers.page.auth.oauth.waiting': '正在等待授权…',
+  'settings.providers.page.auth.oauth.waitingHint': '请在浏览器中完成登录。保持此页面打开，连接会自动完成。',
+  'settings.providers.page.auth.oauth.codeHint': '从浏览器复制授权码并粘贴到此处。',
+  'settings.providers.page.auth.oauth.deviceCodeLabel': '设备码',
+  'settings.providers.page.auth.oauth.linkLabel': '授权链接',
+  'settings.providers.page.auth.oauth.promptRequired': '请填写“{field}”后继续',
+  'settings.providers.page.auth.oauth.error.sessionExpired': '授权请求已过期。请重新连接以重新开始。',
+  'settings.providers.page.auth.oauth.error.codeRequired': '此提供方需要浏览器中的授权码。',
+  'settings.providers.page.auth.oauth.error.declined': '授权被拒绝或未完成。',
+  'settings.providers.page.auth.oauth.error.invalidInput': '输入的信息被拒绝。',
   'settings.providers.page.auth.connected': '已连接',
   'settings.providers.page.auth.incomplete': '缺少凭据',
   'settings.providers.page.auth.incompleteHint': '· 在聊天中使用此提供商之前，请添加 API 密钥或 {env:VAR}',
@@ -1391,6 +1402,9 @@ export const settingsDict = {
   'settings.providers.page.actions.open': '打开',
   'settings.providers.page.actions.copy': '复制',
   'settings.providers.page.actions.complete': '完成',
+  'settings.providers.page.actions.continue': '继续',
+  'settings.providers.page.actions.cancel': '取消',
+  'settings.providers.page.actions.tryAgain': '重试',
   'settings.providers.page.actions.hide': '隐藏',
   'settings.providers.page.actions.reconnect': '重新连接',
   'settings.providers.page.actions.edit': '编辑',
@@ -1406,7 +1420,6 @@ export const settingsDict = {
   'settings.providers.page.toast.apiKeySaved': 'API Key 已保存',
   'settings.providers.page.toast.oauthStartFailed': '启动 OAuth 流程失败',
   'settings.providers.page.toast.oauthDetailsMissing': '未返回 OAuth 详情',
-  'settings.providers.page.toast.completeOAuthInBrowser': '请在浏览器中完成 OAuth 流程',
   'settings.providers.page.toast.oauthCompleteFailed': '完成 OAuth 流程失败',
   'settings.providers.page.toast.oauthCompleted': 'OAuth 连接已完成',
   'settings.providers.page.toast.oauthLinkCopied': 'OAuth 链接已复制',
diff --git a/packages/ui/src/lib/i18n/messages/zh-TW.settings.ts b/packages/ui/src/lib/i18n/messages/zh-TW.settings.ts
index a1d814b0..892dab37 100644
--- a/packages/ui/src/lib/i18n/messages/zh-TW.settings.ts
+++ b/packages/ui/src/lib/i18n/messages/zh-TW.settings.ts
@@ -1265,6 +1265,17 @@
   'settings.providers.page.auth.apiKeyPlaceholder': 'sk-...',
   'settings.providers.page.auth.oauthMethodFallback': 'OAuth 方式 {index}',
   'settings.providers.page.auth.pasteAuthorizationCodePlaceholder': '貼上授權碼',
+  'settings.providers.page.auth.oauth.starting': '正在啟動授權…',
+  'settings.providers.page.auth.oauth.waiting': '正在等待授權…',
+  'settings.providers.page.auth.oauth.waitingHint': '請在瀏覽器中完成登入。保持此頁面開啟，連線會自動完成。',
+  'settings.providers.page.auth.oauth.codeHint': '從瀏覽器複製授權碼並貼上到這裡。',
+  'settings.providers.page.auth.oauth.deviceCodeLabel': '裝置碼',
+  'settings.providers.page.auth.oauth.linkLabel': '授權連結',
+  'settings.providers.page.auth.oauth.promptRequired': '請填寫「{field}」後繼續',
+  'settings.providers.page.auth.oauth.error.sessionExpired': '授權請求已過期。請重新連線以重新開始。',
+  'settings.providers.page.auth.oauth.error.codeRequired': '此提供者需要瀏覽器中的授權碼。',
+  'settings.providers.page.auth.oauth.error.declined': '授權遭拒或未完成。',
+  'settings.providers.page.auth.oauth.error.invalidInput': '輸入的資訊遭拒。',
   'settings.providers.page.auth.connected': '已連線',
   'settings.providers.page.auth.incomplete': '缺少憑證',
   'settings.providers.page.auth.incompleteHint': '· 在聊天中使用此提供者之前，請新增 API 金鑰或 {env:VAR}',
@@ -1297,6 +1308,9 @@
   'settings.providers.page.actions.open': '開啟',
   'settings.providers.page.actions.copy': '複製',
   'settings.providers.page.actions.complete': '完成',
+  'settings.providers.page.actions.continue': '繼續',
+  'settings.providers.page.actions.cancel': '取消',
+  'settings.providers.page.actions.tryAgain': '重試',
   'settings.providers.page.actions.hide': '隱藏',
   'settings.providers.page.actions.reconnect': '重新連線',
   'settings.providers.page.actions.edit': '編輯',
@@ -1312,7 +1326,6 @@
   'settings.providers.page.toast.apiKeySaved': 'API Key 已儲存',
   'settings.providers.page.toast.oauthStartFailed': '啟動 OAuth 流程失敗',
   'settings.providers.page.toast.oauthDetailsMissing': '未回傳 OAuth 詳情',
-  'settings.providers.page.toast.completeOAuthInBrowser': '請在瀏覽器中完成 OAuth 流程',
   'settings.providers.page.toast.oauthCompleteFailed': '完成 OAuth 流程失敗',
   'settings.providers.page.toast.oauthCompleted': 'OAuth 連線已完成',
   'settings.providers.page.toast.oauthLinkCopied': 'OAuth 連結已複製',
diff --git a/packages/web/server/lib/opencode/DOCUMENTATION.md b/packages/web/server/lib/opencode/DOCUMENTATION.md
index 1c625beb..dfd520c0 100644
--- a/packages/web/server/lib/opencode/DOCUMENTATION.md
+++ b/packages/web/server/lib/opencode/DOCUMENTATION.md
@@ -375,6 +375,8 @@ an authoritative loopback callback URL even when OpenChamber binds port `0`.
   - SSE forwarders: `GET /api/global/event`, `GET /api/event`
     - Downstream heartbeats keep clients and intermediaries alive, while a separate upstream-only stall watchdog closes the downstream response when OpenCode stops producing bytes so clients reconnect instead of trusting synthetic heartbeats indefinitely. Each watchdog reset uses the current load-aware timeout, matching the shared event transport.
   - Session message forwarder: `POST /api/session/:sessionId/message`
+  - Interactive OAuth forwarder: `POST /api/provider/:providerID/oauth/callback`
+    - Upstream blocks inside this call for the whole browser sign-in (device-code polling or a loopback redirect), so it is exempt from the ordinary request deadline and uses a 15-minute proxy timeout instead of `LONG_REQUEST_TIMEOUT_MS`. All other `/api/provider/*` routes, including `oauth/authorize`, keep the ordinary deadline.
   - Generic `/api/*` forwarding with hop-by-hop header filtering
   - Windows `/session` merge fallback path behavior
   - OpenCode readiness gate for proxied `/api` requests
diff --git a/packages/web/server/lib/opencode/proxy.js b/packages/web/server/lib/opencode/proxy.js
index 04fecf54..9d1be85b 100644
--- a/packages/web/server/lib/opencode/proxy.js
+++ b/packages/web/server/lib/opencode/proxy.js
@@ -309,6 +309,16 @@ export const registerOpenCodeProxy = (app, deps) => {
   const PROXY_REQUEST_TIMEOUT_MS = normalizeProxyTimeout(LONG_REQUEST_TIMEOUT_MS);
   const PROXY_TIMEOUT_MARKER = Symbol('openchamberProxyTimedOut');
 
+  // A provider OAuth callback blocks upstream for as long as the user takes to
+  // sign in in their browser (device-code polling, or a loopback redirect), so
+  // it cannot share the ordinary request deadline. Bounded by the shortest
+  // upstream expiry we know of — GitHub device codes last ~15 minutes.
+  const INTERACTIVE_OAUTH_TIMEOUT_MS = 15 * 60 * 1000;
+  const INTERACTIVE_OAUTH_PATH = /^\/provider\/[^/]+\/oauth\/callback\/?$/;
+
+  const isInteractiveOAuthCallback = (req) =>
+    req.method === 'POST' && INTERACTIVE_OAUTH_PATH.test(req.path);
+
   const isProxyTimeoutError = (error) => {
     const code = typeof error?.code === 'string' ? error.code : '';
     const message = typeof error?.message === 'string' ? error.message.toLowerCase() : '';
@@ -327,6 +337,10 @@ export const registerOpenCodeProxy = (app, deps) => {
   };
 
   const applyProxyResponseDeadline = (req, res, next) => {
+    if (isInteractiveOAuthCallback(req)) {
+      return next();
+    }
+
     const timeout = setTimeout(() => {
       req[PROXY_TIMEOUT_MARKER] = true;
       if (sendProxyErrorResponse(res, 504)) {
@@ -753,12 +767,12 @@ export const registerOpenCodeProxy = (app, deps) => {
   });
 
   // Generic proxy for non-SSE OpenCode API routes.
-  const apiProxy = createProxyMiddleware({
+  const createApiProxy = (timeoutMs) => createProxyMiddleware({
     target: resolveProxyTarget(),
     changeOrigin: true,
     pathRewrite: { '^/api': '' },
-    timeout: PROXY_REQUEST_TIMEOUT_MS,
-    proxyTimeout: PROXY_REQUEST_TIMEOUT_MS,
+    timeout: timeoutMs,
+    proxyTimeout: timeoutMs,
     // Dynamic target — port can change after restart
     router: () => resolveProxyTarget(),
     on: {
@@ -805,6 +819,9 @@ export const registerOpenCodeProxy = (app, deps) => {
     },
   });
 
+  const apiProxy = createApiProxy(PROXY_REQUEST_TIMEOUT_MS);
+  const interactiveOAuthProxy = createApiProxy(INTERACTIVE_OAUTH_TIMEOUT_MS);
+
   // Best-effort fallback for stale clients still sending symlink paths.
   // Settings and project selection normalize at source; this cached async path
   // avoids blocking the proxy hot path on every directory-scoped request.
@@ -821,5 +838,6 @@ export const registerOpenCodeProxy = (app, deps) => {
   });
 
   app.use('/api', applyProxyResponseDeadline);
+  app.post('/api/provider/:providerID/oauth/callback', interactiveOAuthProxy);
   app.use('/api', apiProxy);
 };
diff --git a/packages/web/server/opencode-proxy.test.js b/packages/web/server/opencode-proxy.test.js
index da8c7f72..2eb1f0cd 100644
--- a/packages/web/server/opencode-proxy.test.js
+++ b/packages/web/server/opencode-proxy.test.js
@@ -623,4 +623,87 @@ describe('OpenCode proxy SSE forwarding', () => {
     expect(response.status).toBe(504);
     await expect(response.json()).resolves.toMatchObject({ error: 'OpenCode upstream timed out' });
   });
+
+  it('exempts interactive provider OAuth callbacks from the request deadline', async () => {
+    const upstream = express();
+    // Stands in for upstream blocking until the user finishes signing in.
+    upstream.post('/provider/:providerID/oauth/callback', async (_req, res) => {
+      await new Promise((resolve) => setTimeout(resolve, 250));
+      res.json(true);
+    });
+    upstreamServer = await listen(upstream);
+    const upstreamPort = upstreamServer.address().port;
+    const externalBaseUrl = `http://127.0.0.1:${upstreamPort}`;
+
+    const app = express();
+    registerOpenCodeProxy(app, {
+      fs: {},
+      os: {},
+      path,
+      OPEN_CODE_READY_GRACE_MS: 0,
+      LONG_REQUEST_TIMEOUT_MS: 50,
+      getRuntime: () => ({
+        openCodePort: upstreamPort,
+        openCodeBaseUrl: externalBaseUrl,
+        isOpenCodeReady: true,
+        openCodeNotReadySince: 0,
+        isRestartingOpenCode: false,
+      }),
+      getOpenCodeAuthHeaders: () => ({}),
+      buildOpenCodeUrl: (requestPath) => `${externalBaseUrl}${requestPath}`,
+      ensureOpenCodeApiPrefix: () => {},
+    });
+    proxyServer = await listen(app);
+    const proxyPort = proxyServer.address().port;
+
+    const response = await fetch(`http://127.0.0.1:${proxyPort}/api/provider/github-copilot/oauth/callback`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ method: 0 }),
+      signal: AbortSignal.timeout(5000),
+    });
+
+    expect(response.status).toBe(200);
+    await expect(response.json()).resolves.toBe(true);
+  });
+
+  it('still applies the request deadline to the OAuth authorize call', async () => {
+    const upstream = express();
+    upstream.post('/provider/:providerID/oauth/authorize', (_req, _res) => {
+      // Leave the response open so the proxy timeout path is exercised.
+    });
+    upstreamServer = await listen(upstream);
+    const upstreamPort = upstreamServer.address().port;
+    const externalBaseUrl = `http://127.0.0.1:${upstreamPort}`;
+
+    const app = express();
+    registerOpenCodeProxy(app, {
+      fs: {},
+      os: {},
+      path,
+      OPEN_CODE_READY_GRACE_MS: 0,
+      LONG_REQUEST_TIMEOUT_MS: 50,
+      getRuntime: () => ({
+        openCodePort: upstreamPort,
+        openCodeBaseUrl: externalBaseUrl,
+        isOpenCodeReady: true,
+        openCodeNotReadySince: 0,
+        isRestartingOpenCode: false,
+      }),
+      getOpenCodeAuthHeaders: () => ({}),
+      buildOpenCodeUrl: (requestPath) => `${externalBaseUrl}${requestPath}`,
+      ensureOpenCodeApiPrefix: () => {},
+    });
+    proxyServer = await listen(app);
+    const proxyPort = proxyServer.address().port;
+
+    const response = await fetch(`http://127.0.0.1:${proxyPort}/api/provider/github-copilot/oauth/authorize`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ method: 0 }),
+      signal: AbortSignal.timeout(2000),
+    });
+
+    expect(response.status).toBe(504);
+  });
 });

From 67965ced2ff1ca6678facd1dcf6dc4ec81e385e7 Mon Sep 17 00:00:00 2001
From: Bohdan Triapitsyn <artmore@protonmail.com>
Date: Tue, 4 Aug 2026 19:39:40 +0300
Subject: [PATCH 11/57] release v1.18.1

---
 CHANGELOG.md                   | 12 ++++++++++++
 bun.lock                       | 18 +++++++++---------
 package.json                   |  4 ++--
 packages/electron/package.json |  2 +-
 packages/ui/package.json       |  4 ++--
 packages/vscode/CHANGELOG.md   |  8 ++++++++
 packages/vscode/package.json   |  4 ++--
 packages/web/package.json      |  4 ++--
 8 files changed, 38 insertions(+), 18 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 22de68b1..ed3da0ab 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,18 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [1.18.1] - 2026-08-04
+
+- **Providers:** signing in to an OAuth-only provider now actually completes — the browser login is stored and the provider list updates instead of remaining signed out. OAuth-only providers show a Connect flow instead of an API key form, and their models stay hidden until you are signed in.
+- **Sessions:** archived sessions can now be restored to the active list — from the sidebar context menu, the archived-sessions page, or the bulk-selection bar — instead of only offering permanent deletion (thanks to @makeittech).
+- Walkthrough: models without a working provider login no longer appear in the walkthrough picker, and Generate stays disabled until a usable model is selected instead of failing with a raw provider error.
+- Providers: sign-ins that need extra details (such as GitHub Copilot Enterprise) now ask for them before opening the browser, and device codes come with a working copy button.
+- Walkthrough: connecting to a server older than the app now says the server needs updating instead of showing a raw HTML parsing error, and the "Critical" tag is now "Key change" with a tooltip so it no longer reads as a problem found in your code.
+- Chat: Ctrl/Cmd+L now adds the selected text to the chat input, or focuses it when nothing is selected; the toggle-sidebar shortcut moved to Ctrl/Cmd+Alt+L.
+- Chat: a manually chosen model now stays selected after a delegated subtask finishes, instead of reverting to the agent's default model.
+- Agents/CLI: sending a prompt that never reaches its session is now reported as failed, and an unavailable model, agent, or variant is rejected with a clear error before anything is created.
+- Desktop/Linux: "Open in Terminal" no longer launches a non-terminal app that is set as the terminal launcher (thanks to @kydorn).
+
 ## [1.18.0] - 2026-08-04
 
 - **Walkthrough:** a new guided walkthrough reorders a diff into a sequence of stops — the model groups related changes, explains what each one does, and orders them so each builds on the last. Start one from the Changes and pull-request views for uncommitted work, a branch against its base, or a pull request; nothing runs on its own. Walkthroughs are written in your interface language by default, and the panel can generate one in any other supported language.
diff --git a/bun.lock b/bun.lock
index 370b1124..cd8e95ab 100644
--- a/bun.lock
+++ b/bun.lock
@@ -30,7 +30,7 @@
         "@heroui/theme": "^2.4.23",
         "@lezer/highlight": "^1.2.3",
         "@octokit/rest": "^22.0.1",
-        "@opencode-ai/sdk": "1.18.11",
+        "@opencode-ai/sdk": "1.18.12",
         "@radix-ui/react-collapsible": "^1.1.12",
         "@radix-ui/react-dialog": "^1.1.15",
         "@radix-ui/react-dropdown-menu": "^2.1.16",
@@ -95,7 +95,7 @@
     },
     "packages/electron": {
       "name": "@openchamber/electron",
-      "version": "1.17.2",
+      "version": "1.18.0",
       "dependencies": {
         "@openchamber/web": "workspace:*",
         "electron-context-menu": "^4.1.2",
@@ -131,7 +131,7 @@
     },
     "packages/ui": {
       "name": "@openchamber/ui",
-      "version": "1.17.2",
+      "version": "1.18.0",
       "dependencies": {
         "@aparajita/capacitor-secure-storage": "^8.0.0",
         "@base-ui/react": "^1.4.0",
@@ -165,7 +165,7 @@
         "@dnd-kit/sortable": "^10.0.0",
         "@dnd-kit/utilities": "^3.2.2",
         "@lezer/highlight": "^1.2.3",
-        "@opencode-ai/sdk": "1.18.11",
+        "@opencode-ai/sdk": "1.18.12",
         "@pierre/diffs": "1.3.0-beta.6",
         "@replit/codemirror-vim": "^6.3.0",
         "@simplewebauthn/browser": "13.3.0",
@@ -236,10 +236,10 @@
     },
     "packages/vscode": {
       "name": "openchamber",
-      "version": "1.17.2",
+      "version": "1.18.0",
       "dependencies": {
         "@openchamber/ui": "workspace:*",
-        "@opencode-ai/sdk": "1.18.11",
+        "@opencode-ai/sdk": "1.18.12",
         "adm-zip": "^0.5.16",
         "jsonc-parser": "^3.3.1",
         "react": "^19.1.1",
@@ -259,14 +259,14 @@
     },
     "packages/web": {
       "name": "@openchamber/web",
-      "version": "1.17.2",
+      "version": "1.18.0",
       "bin": {
         "openchamber": "./bin/cli.js",
       },
       "dependencies": {
         "@clack/prompts": "^1.1.0",
         "@octokit/rest": "^22.0.1",
-        "@opencode-ai/sdk": "1.18.11",
+        "@opencode-ai/sdk": "1.18.12",
         "@simplewebauthn/server": "13.3.1",
         "adm-zip": "^0.5.16",
         "bun-pty": "^0.4.5",
@@ -997,7 +997,7 @@
 
     "@openchamber/web": ["@openchamber/web@workspace:packages/web"],
 
-    "@opencode-ai/sdk": ["@opencode-ai/sdk@1.18.11", "", { "dependencies": { "cross-spawn": "7.0.6" } }, "sha512-yDImmNv4PhxdMgtiHVNWQWEVwQlAm7Dr0y4XU7CT4dOIbzgO+VP+9I02lAP7Zva1FhGeyI7oKMI2tzB9RUsWaQ=="],
+    "@opencode-ai/sdk": ["@opencode-ai/sdk@1.18.12", "", { "dependencies": { "cross-spawn": "7.0.6" } }, "sha512-Skjm0uRWqIiL9BQliZSrvnBflT99q1aGhT2pATNwli2WU8XSKm4lhZJFay7dIzjrA5C9SfgK+YSeoES2PbFugA=="],
 
     "@paralleldrive/cuid2": ["@paralleldrive/cuid2@2.3.1", "", { "dependencies": { "@noble/hashes": "^1.1.5" } }, "sha512-XO7cAxhnTZl0Yggq6jOgjiOHhbgcO4NqFqwSmQpjK3b6TEE6Uj/jfSk6wzYyemh3+I0sHirKSetjQwn5cZktFw=="],
 
diff --git a/package.json b/package.json
index ac088390..81c55465 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "openchamber-monorepo",
-  "version": "1.18.0",
+  "version": "1.18.1",
   "description": "OpenChamber monorepo workspace for web, ui, and desktop runtimes",
   "private": true,
   "type": "module",
@@ -112,7 +112,7 @@
     "@heroui/theme": "^2.4.23",
     "@lezer/highlight": "^1.2.3",
     "@octokit/rest": "^22.0.1",
-    "@opencode-ai/sdk": "1.18.11",
+    "@opencode-ai/sdk": "1.18.12",
     "@radix-ui/react-collapsible": "^1.1.12",
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
diff --git a/packages/electron/package.json b/packages/electron/package.json
index 67800186..88b3592a 100644
--- a/packages/electron/package.json
+++ b/packages/electron/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openchamber/electron",
-  "version": "1.18.0",
+  "version": "1.18.1",
   "private": true,
   "description": "Electron desktop runtime for OpenChamber",
   "author": "OpenChamber",
diff --git a/packages/ui/package.json b/packages/ui/package.json
index b5aab832..252ca74a 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openchamber/ui",
-  "version": "1.18.0",
+  "version": "1.18.1",
   "private": true,
   "type": "module",
   "main": "src/main.tsx",
@@ -43,7 +43,7 @@
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
     "@lezer/highlight": "^1.2.3",
-    "@opencode-ai/sdk": "1.18.11",
+    "@opencode-ai/sdk": "1.18.12",
     "@pierre/diffs": "1.3.0-beta.6",
     "@replit/codemirror-vim": "^6.3.0",
     "@simplewebauthn/browser": "13.3.0",
diff --git a/packages/vscode/CHANGELOG.md b/packages/vscode/CHANGELOG.md
index 77f468aa..19bd1fef 100644
--- a/packages/vscode/CHANGELOG.md
+++ b/packages/vscode/CHANGELOG.md
@@ -1,3 +1,11 @@
+## [1.18.1] - 2026-08-04
+
+- **Providers:** signing in to an OAuth-only provider (such as Cursor) now completes in the browser — the login is stored and the provider updates instead of remaining signed out. OAuth-only providers show a Connect flow instead of an API key form, and their models stay hidden until you are signed in.
+- **Sessions:** archived sessions can now be restored to the active list — from the sidebar context menu, the archived-sessions page, or the bulk-selection bar (thanks to @makeittech).
+- Providers: sign-ins that need extra details (such as GitHub Copilot Enterprise) now ask for them before opening the browser, and device codes come with a working copy button.
+- Chat: a manually chosen model now stays selected after a delegated subtask finishes, instead of reverting to the agent's default model.
+- Chat: Ctrl/Cmd+L now adds the selected text to the chat input, or focuses it when nothing is selected.
+
 ## [1.18.0] - 2026-08-04
 
 - **Providers:** custom OpenAI-compatible providers can now be added and edited from Settings, including their endpoint, models, credentials, headers, and configuration scope (thanks to @makeittech).
diff --git a/packages/vscode/package.json b/packages/vscode/package.json
index eb796875..feea88ca 100644
--- a/packages/vscode/package.json
+++ b/packages/vscode/package.json
@@ -2,7 +2,7 @@
   "name": "openchamber",
   "displayName": "OpenChamber",
   "description": "%extension.description%",
-  "version": "1.18.0",
+  "version": "1.18.1",
   "publisher": "fedaykindev",
   "private": true,
   "repository": {
@@ -244,7 +244,7 @@
   },
   "dependencies": {
     "@openchamber/ui": "workspace:*",
-    "@opencode-ai/sdk": "1.18.11",
+    "@opencode-ai/sdk": "1.18.12",
     "adm-zip": "^0.5.16",
     "jsonc-parser": "^3.3.1",
     "react": "^19.1.1",
diff --git a/packages/web/package.json b/packages/web/package.json
index ba63d58f..46b04352 100644
--- a/packages/web/package.json
+++ b/packages/web/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openchamber/web",
-  "version": "1.18.0",
+  "version": "1.18.1",
   "private": false,
   "type": "module",
   "main": "./server/index.js",
@@ -25,7 +25,7 @@
   "dependencies": {
     "@clack/prompts": "^1.1.0",
     "@octokit/rest": "^22.0.1",
-    "@opencode-ai/sdk": "1.18.11",
+    "@opencode-ai/sdk": "1.18.12",
     "@simplewebauthn/server": "13.3.1",
     "adm-zip": "^0.5.16",
     "bun-pty": "^0.4.5",

From b4ced01cc70e7e6ab0072efe239c30b07a082d0d Mon Sep 17 00:00:00 2001
From: RyderAsking <clasherlodt@gmail.com>
Date: Tue, 4 Aug 2026 16:48:17 +0000
Subject: [PATCH 12/57] fix(walkthrough): use remote default branch

---
 .../components/views/git/baseBranch.test.ts   | 30 +++++++++++++++++++
 .../ui/src/components/views/git/baseBranch.ts | 15 ++++++++++
 .../views/walkthrough/WalkthroughView.tsx     | 30 +++++++++++++------
 packages/ui/src/lib/api/types.ts              |  1 +
 packages/web/server/lib/git/DOCUMENTATION.md  |  1 +
 packages/web/server/lib/git/service.js        | 26 +++++++++++++++-
 packages/web/server/lib/git/service.test.js   | 23 ++++++++++++++
 .../server/lib/walkthrough/DOCUMENTATION.md   |  5 ++++
 8 files changed, 121 insertions(+), 10 deletions(-)
 create mode 100644 packages/ui/src/components/views/git/baseBranch.test.ts

diff --git a/packages/ui/src/components/views/git/baseBranch.test.ts b/packages/ui/src/components/views/git/baseBranch.test.ts
new file mode 100644
index 00000000..18aaffb8
--- /dev/null
+++ b/packages/ui/src/components/views/git/baseBranch.test.ts
@@ -0,0 +1,30 @@
+import { describe, expect, test } from 'bun:test';
+import { deriveBaseBranch, hasResolvableBaseBranch } from './baseBranch';
+
+describe('deriveBaseBranch', () => {
+  test('prefers the remote default branch hint over conventional fallbacks', () => {
+    expect(deriveBaseBranch({
+      remoteNames: new Set(['origin']),
+      localBranches: ['next'],
+      rootBranchHint: 'origin/react',
+    })).toBe('react');
+  });
+});
+
+describe('hasResolvableBaseBranch', () => {
+  test('rejects the main fallback when it does not exist', () => {
+    expect(hasResolvableBaseBranch({
+      baseBranch: 'main',
+      localBranches: ['next', 'react'],
+      remoteBranches: ['origin/next', 'origin/react'],
+    })).toBe(false);
+  });
+
+  test('accepts a base branch available through a remote-tracking ref', () => {
+    expect(hasResolvableBaseBranch({
+      baseBranch: 'main',
+      localBranches: ['next'],
+      remoteBranches: ['origin/main', 'origin/next'],
+    })).toBe(true);
+  });
+});
diff --git a/packages/ui/src/components/views/git/baseBranch.ts b/packages/ui/src/components/views/git/baseBranch.ts
index 19e22b59..6409597b 100644
--- a/packages/ui/src/components/views/git/baseBranch.ts
+++ b/packages/ui/src/components/views/git/baseBranch.ts
@@ -62,3 +62,18 @@ export const deriveBaseBranch = (options: {
   if (localBranches.includes('develop')) return 'develop';
   return 'main';
 };
+
+/**
+ * Whether a base branch can be resolved locally or through one of the active
+ * remote-tracking refs. Callers must not offer comparisons against the `main`
+ * fallback when that ref does not actually exist in the repository.
+ */
+export const hasResolvableBaseBranch = (options: {
+  baseBranch: string;
+  localBranches: readonly string[];
+  remoteBranches: readonly string[];
+}): boolean => {
+  const { baseBranch, localBranches, remoteBranches } = options;
+  return localBranches.includes(baseBranch)
+    || remoteBranches.some((branch) => branch.endsWith(`/${baseBranch}`));
+};
diff --git a/packages/ui/src/components/views/walkthrough/WalkthroughView.tsx b/packages/ui/src/components/views/walkthrough/WalkthroughView.tsx
index 246a818c..a2c2527b 100644
--- a/packages/ui/src/components/views/walkthrough/WalkthroughView.tsx
+++ b/packages/ui/src/components/views/walkthrough/WalkthroughView.tsx
@@ -14,10 +14,10 @@ import { useI18n, type Locale } from '@/lib/i18n';
 import { buildWalkthroughView } from '@/lib/walkthrough/model';
 import type { WalkthroughSource, WalkthroughWorkingTreeScope } from '@/lib/walkthrough/types';
 import { ModelSelector } from '@/components/sections/agents/ModelSelector';
-import { deriveBaseBranch } from '@/components/views/git/baseBranch';
+import { deriveBaseBranch, hasResolvableBaseBranch } from '@/components/views/git/baseBranch';
 import { runtimeFetch } from '@/lib/runtime-fetch';
 import { useConfigStore } from '@/stores/useConfigStore';
-import { useGitBranches, useGitStatus } from '@/stores/useGitStore';
+import { useGitBranches, useGitStatus, useGitStore } from '@/stores/useGitStore';
 import { useGitHubAuthStore } from '@/stores/useGitHubAuthStore';
 import {
   getFreshestPrStatusForBranch,
@@ -152,6 +152,12 @@ export const WalkthroughView = ({ directory }: WalkthroughViewProps) => {
 
   const status = useGitStatus(directory || null);
   const branches = useGitBranches(directory || null);
+  const ensureAll = useGitStore((state) => state.ensureAll);
+  const { github, git } = useRuntimeAPIs();
+
+  useEffect(() => {
+    if (directory) void ensureAll(directory, git);
+  }, [directory, ensureAll, git]);
 
   // The branch source reviews everything on this branch that is not on its
   // base. Three-dot semantics server-side mean merges from the base are
@@ -162,22 +168,28 @@ export const WalkthroughView = ({ directory }: WalkthroughViewProps) => {
     if (!headRef) return null;
     const all = branches?.all ?? [];
     const localBranches = all.filter((name) => !name.startsWith('remotes/'));
+    const remoteBranches = all
+      .filter((name) => name.startsWith('remotes/'))
+      .map((name) => name.slice('remotes/'.length));
     const remoteNames = new Set(
-      all
-        .filter((name) => name.startsWith('remotes/'))
-        .map((name) => name.slice('remotes/'.length).split('/')[0])
+      remoteBranches
+        .map((name) => name.split('/')[0])
         .filter(Boolean)
     );
-    const baseRef = deriveBaseBranch({ remoteNames, localBranches });
-    if (!baseRef || baseRef === headRef) return null;
+    const trackingRemote = status?.tracking?.split('/')[0];
+    const rootBranchHint = (trackingRemote && branches?.defaultBranches?.[trackingRemote])
+      ?? branches?.defaultBranches?.origin;
+    const baseRef = deriveBaseBranch({ remoteNames, localBranches, rootBranchHint });
+    if (!baseRef || baseRef === headRef || !hasResolvableBaseBranch({ baseBranch: baseRef, localBranches, remoteBranches })) {
+      return null;
+    }
     return { kind: 'branch', baseRef, headRef };
-  }, [branches, currentBranch]);
+  }, [branches, currentBranch, status?.tracking]);
 
   // The pull request for this branch used to appear only after visiting the PR
   // panel, because nothing else asked GitHub about it. Ask here too: the status
   // store already dedupes by signature and throttles by TTL, so several panels
   // wanting the same answer produce one request.
-  const { github } = useRuntimeAPIs();
   const githubConnected = useGitHubAuthStore((state) => state.status?.connected ?? false);
   const githubAuthChecked = useGitHubAuthStore((state) => state.hasChecked);
   const ensurePrStatusEntry = useGitHubPrStatusStore((state) => state.ensureEntry);
diff --git a/packages/ui/src/lib/api/types.ts b/packages/ui/src/lib/api/types.ts
index 9b1ae0b7..9c5859af 100644
--- a/packages/ui/src/lib/api/types.ts
+++ b/packages/ui/src/lib/api/types.ts
@@ -183,6 +183,7 @@ export interface GitBranch {
   all: string[];
   current: string;
   branches: Record<string, GitBranchDetails>;
+  defaultBranches?: Record<string, string>;
 }
 
 interface GitCommitSummary {
diff --git a/packages/web/server/lib/git/DOCUMENTATION.md b/packages/web/server/lib/git/DOCUMENTATION.md
index 7dbd31ce..8bcbb964 100644
--- a/packages/web/server/lib/git/DOCUMENTATION.md
+++ b/packages/web/server/lib/git/DOCUMENTATION.md
@@ -105,6 +105,7 @@ The following functions are internal helpers used by exported functions:
 - `ahead`: Number of commits ahead of upstream.
 - `behind`: Number of commits behind upstream.
 - `upstreamComparison`: Optional comparison against `upstream/<current-branch>`, with `{ remote, branch, ahead, behind }`.
+- `defaultBranches`: Remote default branches derived from local symbolic refs such as `remotes/origin/HEAD -> origin/main`, keyed by remote name. Omitted by runtimes that do not provide this Git metadata.
 - `files`: Array of file objects with `path`, `index`, `working_dir` status codes.
 - `isClean`: Boolean indicating if working tree is clean.
 - `diffStats`: Object mapping file paths to `{ insertions, deletions }`.
diff --git a/packages/web/server/lib/git/service.js b/packages/web/server/lib/git/service.js
index a3a99f62..ed64b7c5 100644
--- a/packages/web/server/lib/git/service.js
+++ b/packages/web/server/lib/git/service.js
@@ -3367,6 +3367,7 @@ export async function getBranches(directory) {
     const allBranches = result.all;
     const remoteBranches = allBranches.filter(branch => branch.startsWith('remotes/'));
     const activeRemoteBranches = await filterActiveRemoteBranches(git, remoteBranches);
+    const defaultBranches = await getRemoteDefaultBranches(git);
 
     const filteredAll = [
       ...allBranches.filter(branch => !branch.startsWith('remotes/')),
@@ -3376,7 +3377,8 @@ export async function getBranches(directory) {
     return {
       all: filteredAll,
       current: result.current,
-      branches: result.branches
+      branches: result.branches,
+      defaultBranches,
     };
   } catch (error) {
     console.error('Failed to get branches:', error);
@@ -3384,6 +3386,28 @@ export async function getBranches(directory) {
   }
 }
 
+async function getRemoteDefaultBranches(git) {
+  try {
+    const refs = await git.raw([
+      'for-each-ref',
+      '--format=%(refname) %(symref)',
+      'refs/remotes',
+    ]);
+    return Object.fromEntries(
+      refs.trim().split('\n').flatMap((line) => {
+        const [ref, symbolicRef] = line.split(' ');
+        const match = ref.match(/^refs\/remotes\/([^/]+)\/HEAD$/);
+        const prefix = match ? `refs/remotes/${match[1]}/` : '';
+        return match && typeof symbolicRef === 'string' && symbolicRef.startsWith(prefix)
+          ? [[match[1], symbolicRef.slice(prefix.length)]]
+          : [];
+      })
+    );
+  } catch {
+    return {};
+  }
+}
+
 async function filterActiveRemoteBranches(git, remoteBranches) {
   try {
     const remotes = await git.getRemotes();
diff --git a/packages/web/server/lib/git/service.test.js b/packages/web/server/lib/git/service.test.js
index e5110995..40f0c054 100644
--- a/packages/web/server/lib/git/service.test.js
+++ b/packages/web/server/lib/git/service.test.js
@@ -10,6 +10,7 @@ import {
   cherryPick,
   createWorktree,
   getWorktreeBootstrapStatus,
+  getBranches,
   getStatus,
   isGitRepository,
   populateWorktreeWithLockRecovery,
@@ -988,3 +989,25 @@ describe('hash validation', () => {
     ).rejects.not.toThrow('Invalid commit hash');
   });
 });
+
+describe.runIf(canRunGit())('getBranches', () => {
+  it('returns a remote default branch whose name is not a conventional fallback', async () => {
+    const remote = createTempDir();
+    const repository = createTempDir();
+    runGit(remote, ['init', '--bare', '--initial-branch=react']);
+    runGit(repository, ['init', '-b', 'next']);
+    runGit(repository, ['config', 'user.email', 'test@example.com']);
+    runGit(repository, ['config', 'user.name', 'Test']);
+    fs.writeFileSync(path.join(repository, 'README.md'), '# Test\n');
+    runGit(repository, ['add', 'README.md']);
+    runGit(repository, ['commit', '-m', 'init']);
+    runGit(repository, ['remote', 'add', 'origin', remote]);
+    runGit(repository, ['push', 'origin', 'HEAD:react']);
+    runGit(repository, ['fetch', 'origin']);
+    runGit(repository, ['remote', 'set-head', 'origin', '--auto']);
+
+    await expect(getBranches(repository)).resolves.toMatchObject({
+      defaultBranches: { origin: 'react' },
+    });
+  });
+});
diff --git a/packages/web/server/lib/walkthrough/DOCUMENTATION.md b/packages/web/server/lib/walkthrough/DOCUMENTATION.md
index 0f23fac5..b2d43ad1 100644
--- a/packages/web/server/lib/walkthrough/DOCUMENTATION.md
+++ b/packages/web/server/lib/walkthrough/DOCUMENTATION.md
@@ -55,6 +55,11 @@ written against staged code never silently re-anchors onto an unstaged edit.
 | `branch` | `branch` | `getRangeDiff` uses three-dot `base...head`, so work merged in from the base branch is excluded |
 | `pr` | `pr:<number>` | GitHub returns the merge-base diff, matching the branch semantics |
 
+For the current-branch source, the UI prefers the default branch of the current
+branch's tracking remote (from its local `remote/HEAD` symbolic ref), then uses
+the existing conventional-branch fallback. It does not offer the source when the
+chosen base cannot be resolved locally or through a remote-tracking ref.
+
 The panel offers the current branch's pull request on its own: it registers with
 the shared GitHub PR status store (`useGitHubPrStatusStore`) rather than waiting
 for the pull request panel to have been visited. That store already dedupes

From f3dd89420918be162f8308bc94427291927c10ae Mon Sep 17 00:00:00 2001
From: Bohdan Triapitsyn <artmore@protonmail.com>
Date: Tue, 4 Aug 2026 20:39:45 +0300
Subject: [PATCH 13/57] feat(ui): numbered context-panel surface switching with
 configurable prefix

- Add switch_context_surface shortcut (default Cmd/Ctrl + 1..9, 0 for the 10th
  surface) that opens/closes/switches context panel rail surfaces by their
  visible order, configurable and persisted in Settings -> Shortcuts.
- Show order-number badges on rail icons while the modifier is held >500ms;
  dismiss on release, blur, or a number press until the next press-and-hold.
- Remove the legacy mod+2/3/4 (diff/terminal/git) and switch_tab_1..9 bindings
  so numbered surface switching goes only through the new mechanism.
- Replace the help-dialog 'Switch Project' row with the surface-switch row and
  update the shortcuts footer/header icons to the command icon.
---
 .../components/layout/ContextPanelRail.tsx    | 126 +++++++++--
 .../openchamber/KeyboardShortcutsSettings.tsx |  45 +++-
 .../session/sidebar/SidebarFooter.tsx         |   2 +-
 packages/ui/src/components/ui/HelpDialog.tsx  |  12 +-
 packages/ui/src/hooks/useKeyboardShortcuts.ts |  79 ++++++-
 .../ui/src/lib/i18n/messages/de.settings.ts   |   2 +
 packages/ui/src/lib/i18n/messages/de.ts       |   2 +-
 .../ui/src/lib/i18n/messages/en.settings.ts   |   2 +
 packages/ui/src/lib/i18n/messages/en.ts       |   2 +-
 .../ui/src/lib/i18n/messages/es.settings.ts   |   2 +
 packages/ui/src/lib/i18n/messages/es.ts       |   2 +-
 .../ui/src/lib/i18n/messages/fr.settings.ts   |   2 +
 packages/ui/src/lib/i18n/messages/fr.ts       |   2 +-
 .../ui/src/lib/i18n/messages/ja.settings.ts   |   2 +
 packages/ui/src/lib/i18n/messages/ja.ts       |   2 +-
 .../ui/src/lib/i18n/messages/ko.settings.ts   |   2 +
 packages/ui/src/lib/i18n/messages/ko.ts       |   2 +-
 .../ui/src/lib/i18n/messages/pl.settings.ts   |   2 +
 packages/ui/src/lib/i18n/messages/pl.ts       |   2 +-
 .../src/lib/i18n/messages/pt-BR.settings.ts   |   2 +
 packages/ui/src/lib/i18n/messages/pt-BR.ts    |   2 +-
 .../ui/src/lib/i18n/messages/uk.settings.ts   |   2 +
 packages/ui/src/lib/i18n/messages/uk.ts       |   2 +-
 .../src/lib/i18n/messages/zh-CN.settings.ts   |   2 +
 packages/ui/src/lib/i18n/messages/zh-CN.ts    |   2 +-
 .../src/lib/i18n/messages/zh-TW.settings.ts   |   2 +
 packages/ui/src/lib/i18n/messages/zh-TW.ts    |   2 +-
 packages/ui/src/lib/shortcuts.test.ts         |  80 +++++++
 packages/ui/src/lib/shortcuts.ts              | 213 ++++++++++++------
 packages/ui/src/lib/surfaces/DOCUMENTATION.md |   7 +
 packages/ui/src/lib/surfaces/registry.test.ts |  53 +++++
 packages/ui/src/lib/surfaces/registry.ts      |  37 +++
 32 files changed, 574 insertions(+), 124 deletions(-)
 create mode 100644 packages/ui/src/lib/shortcuts.test.ts
 create mode 100644 packages/ui/src/lib/surfaces/registry.test.ts

diff --git a/packages/ui/src/components/layout/ContextPanelRail.tsx b/packages/ui/src/components/layout/ContextPanelRail.tsx
index 5d522e5c..43692cbb 100644
--- a/packages/ui/src/components/layout/ContextPanelRail.tsx
+++ b/packages/ui/src/components/layout/ContextPanelRail.tsx
@@ -24,18 +24,23 @@ import { useDeviceInfo } from '@/lib/device';
 import { isVSCodeRuntime } from '@/lib/desktop';
 import { useI18n } from '@/lib/i18n';
 import {
+  getVisibleContextRailSurfaces,
   sortContextSurfaces,
   type ContextSurfaceDescriptor,
 } from '@/lib/surfaces/registry';
+import {
+  getEffectiveShortcutPrefix,
+  isShortcutPrefixHeld,
+} from '@/lib/shortcuts';
 import { cn } from '@/lib/utils';
 import { useFeatureFlagsStore } from '@/stores/useFeatureFlagsStore';
 import { useGitStatus } from '@/stores/useGitStore';
 import { normalizeContextPanelDirectoryKey, useUIStore } from '@/stores/useUIStore';
 
 const RAIL_TOOLTIP_DELAY_MS = 150;
-// Tablet width and up: below this the walkthrough cannot show a stop and its
-// code side by side, which is the whole point of the surface.
-const WALKTHROUGH_MIN_WIDTH = 768;
+// Hold the surface-switch modifier for this long before revealing the order
+// number badges on the rail icons.
+const RAIL_NUMBER_HOLD_DELAY_MS = 500;
 const EMPTY_TABS: never[] = [];
 
 type RailItemProps = {
@@ -44,6 +49,8 @@ type RailItemProps = {
   showActivityDot: boolean;
   label: string;
   description: string;
+  orderNumber?: number | null;
+  showOrderNumber?: boolean;
   onSelect: (surface: ContextSurfaceDescriptor) => void;
 };
 
@@ -53,6 +60,8 @@ const ContextPanelRailItem: React.FC<RailItemProps> = ({
   showActivityDot,
   label,
   description,
+  orderNumber,
+  showOrderNumber,
   onSelect,
 }) => {
   const { attributes, listeners, setNodeRef, transform, transition, isDragging } = useSortable({
@@ -86,12 +95,20 @@ const ContextPanelRailItem: React.FC<RailItemProps> = ({
             ) : (
               <Icon name={surface.icon} className="h-[18px] w-[18px]" />
             )}
-            {showActivityDot ? (
+            {showActivityDot && !showOrderNumber ? (
               <span
                 aria-hidden="true"
                 className="absolute right-1 top-1 h-1.5 w-1.5 rounded-full bg-[var(--status-info)]"
               />
             ) : null}
+            {showOrderNumber && orderNumber != null ? (
+              <span
+                aria-hidden="true"
+                className="absolute right-0 top-0 flex h-4 min-w-4 items-center justify-center rounded-full bg-surface-muted px-1 text-[0.625rem] font-medium leading-none text-muted-foreground"
+              >
+                {orderNumber === 10 ? '0' : orderNumber}
+              </span>
+            ) : null}
           </button>
         </TooltipTrigger>
         <TooltipContent side="left" sideOffset={8}>
@@ -114,10 +131,86 @@ export const ContextPanelRail: React.FC = () => {
   const contextRailOrder = useUIStore((state) => state.contextRailOrder);
   const setContextRailOrder = useUIStore((state) => state.setContextRailOrder);
   const openContextSurface = useUIStore((state) => state.openContextSurface);
+  const shortcutOverrides = useUIStore((state) => state.shortcutOverrides);
   const planModeEnabled = useFeatureFlagsStore((state) => state.planModeEnabled);
   const { screenWidth } = useDeviceInfo();
   const gitStatus = useGitStatus(directoryKey || null);
 
+  const surfaceSwitchPrefix = React.useMemo(
+    () => getEffectiveShortcutPrefix('switch_context_surface', shortcutOverrides),
+    [shortcutOverrides],
+  );
+  const [revealNumbers, setRevealNumbers] = React.useState(false);
+
+  // While the surface-switch modifier is held for RAIL_NUMBER_HOLD_DELAY_MS,
+  // reveal the order number badges so users can see which digit maps to which
+  // rail icon. Releasing (or losing focus) dismisses them, and pressing a
+  // number key while the chord is armed consumes them for this hold — they
+  // only come back on the next press-and-hold.
+  React.useEffect(() => {
+    const held = new Set<string>();
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    let consumedWhileHeld = false;
+
+    const isDigitKey = (key: string) => key.length === 1 && key >= '0' && key <= '9';
+
+    const update = () => {
+      const armed = isShortcutPrefixHeld(surfaceSwitchPrefix, held);
+      if (armed) {
+        if (!consumedWhileHeld && timer === null) {
+          timer = setTimeout(() => setRevealNumbers(true), RAIL_NUMBER_HOLD_DELAY_MS);
+        }
+      } else {
+        consumedWhileHeld = false;
+        if (timer !== null) {
+          clearTimeout(timer);
+          timer = null;
+        }
+        setRevealNumbers(false);
+      }
+    };
+
+    const onKeyDown = (e: KeyboardEvent) => {
+      held.add(e.key.toLowerCase());
+      if (isDigitKey(e.key) && isShortcutPrefixHeld(surfaceSwitchPrefix, held)) {
+        consumedWhileHeld = true;
+        if (timer !== null) {
+          clearTimeout(timer);
+          timer = null;
+        }
+        setRevealNumbers(false);
+        return;
+      }
+      update();
+    };
+    const onKeyUp = (e: KeyboardEvent) => {
+      held.delete(e.key.toLowerCase());
+      update();
+    };
+    const onWindowBlur = () => {
+      held.clear();
+      consumedWhileHeld = false;
+      if (timer !== null) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      setRevealNumbers(false);
+    };
+
+    window.addEventListener('keydown', onKeyDown, true);
+    window.addEventListener('keyup', onKeyUp, true);
+    window.addEventListener('blur', onWindowBlur);
+
+    return () => {
+      window.removeEventListener('keydown', onKeyDown, true);
+      window.removeEventListener('keyup', onKeyUp, true);
+      window.removeEventListener('blur', onWindowBlur);
+      if (timer !== null) {
+        clearTimeout(timer);
+      }
+    };
+  }, [surfaceSwitchPrefix]);
+
   const sensors = useSensors(
     useSensor(MouseSensor, { activationConstraint: { distance: 8 } }),
     useSensor(TouchSensor, { activationConstraint: { delay: 200, tolerance: 6 } }),
@@ -128,22 +221,13 @@ export const ContextPanelRail: React.FC = () => {
   const activeMode = panelState?.isOpen ? activeTab?.mode ?? null : null;
   const changedFilesCount = gitStatus?.files.length ?? 0;
 
-  // Content-driven surfaces are hidden (not disabled) until content exists;
-  // an existing tab keeps them visible even if the content source went away.
   const surfaces = React.useMemo(() => {
-    return sortContextSurfaces(contextRailOrder).filter((surface) => {
-      if (surface.id === 'plan' && !planModeEnabled) {
-        return false;
-      }
-      // The walkthrough needs room for a stop list beside real code, and its
-      // diffs come from OpenChamber's Git routes, which VS Code does not serve.
-      if (surface.id === 'walkthrough' && (isVSCodeRuntime() || screenWidth < WALKTHROUGH_MIN_WIDTH)) {
-        return false;
-      }
-      if (surface.availability === 'has-content') {
-        return tabs.some((tab) => tab.mode === surface.mode);
-      }
-      return true;
+    return getVisibleContextRailSurfaces({
+      railOrder: contextRailOrder,
+      planModeEnabled,
+      isVSCode: isVSCodeRuntime(),
+      screenWidth,
+      tabs,
     });
   }, [contextRailOrder, planModeEnabled, screenWidth, tabs]);
 
@@ -174,7 +258,7 @@ export const ContextPanelRail: React.FC = () => {
     >
       <DndContext sensors={sensors} collisionDetection={closestCenter} onDragEnd={handleDragEnd}>
         <SortableContext items={surfaces.map((surface) => surface.id)} strategy={verticalListSortingStrategy}>
-          {surfaces.map((surface) => (
+          {surfaces.map((surface, index) => (
             <ContextPanelRailItem
               key={surface.id}
               surface={surface}
@@ -182,6 +266,8 @@ export const ContextPanelRail: React.FC = () => {
               showActivityDot={surface.id === 'git' && changedFilesCount > 0}
               label={t(surface.labelKey)}
               description={t(surface.descriptionKey)}
+              orderNumber={index + 1}
+              showOrderNumber={revealNumbers}
               onSelect={(selected) => openContextSurface(directoryKey, selected.mode)}
             />
           ))}
diff --git a/packages/ui/src/components/sections/openchamber/KeyboardShortcutsSettings.tsx b/packages/ui/src/components/sections/openchamber/KeyboardShortcutsSettings.tsx
index 06a13f20..1956615c 100644
--- a/packages/ui/src/components/sections/openchamber/KeyboardShortcutsSettings.tsx
+++ b/packages/ui/src/components/sections/openchamber/KeyboardShortcutsSettings.tsx
@@ -13,6 +13,7 @@ import {
   formatShortcutForDisplay,
   getCustomizableShortcutActions,
   getEffectiveShortcutCombo,
+  getEffectiveShortcutPrefix,
   isRiskyBrowserShortcut,
   keyToShortcutToken,
   normalizeCombo,
@@ -49,6 +50,35 @@ const keyboardEventToCombo = (event: React.KeyboardEvent<HTMLInputElement>): Sho
   return normalizeCombo(parts.join('+'));
 };
 
+// Prefix capture for chord-style shortcuts (e.g. "switch context panel
+// surface"): a bare modifier press is accepted so the prefix can be just the
+// primary modifier (default) or a modifier + key chord like `mod+p`.
+const keyboardEventToPrefixCombo = (event: React.KeyboardEvent<HTMLInputElement>): ShortcutCombo | null => {
+  const parts: string[] = [];
+
+  if (event.metaKey || event.ctrlKey) {
+    parts.push('mod');
+  }
+  if (event.shiftKey) {
+    parts.push('shift');
+  }
+  if (event.altKey) {
+    parts.push('alt');
+  }
+
+  if (MODIFIER_KEYS.has(event.key.toLowerCase())) {
+    return parts.length > 0 ? normalizeCombo(parts.join('+')) : null;
+  }
+
+  const keyToken = keyToShortcutToken(event.key);
+  if (!keyToken) {
+    return null;
+  }
+
+  parts.push(keyToken);
+  return parts.length > 0 ? normalizeCombo(parts.join('+')) : null;
+};
+
 export const KeyboardShortcutsSettings: React.FC = () => {
   const { t } = useI18n();
   const tUnsafe = React.useCallback((key: string) => t(key as Parameters<typeof t>[0]), [t]);
@@ -211,10 +241,19 @@ export const KeyboardShortcutsSettings: React.FC = () => {
 
       <div>
         {actions.map((action, index) => {
-          const effective = getEffectiveShortcutCombo(action.id, shortcutOverrides);
+          const isSurfaceSwitch = action.id === 'switch_context_surface';
+          const effective = isSurfaceSwitch
+            ? getEffectiveShortcutPrefix(action.id, shortcutOverrides)
+            : getEffectiveShortcutCombo(action.id, shortcutOverrides);
           const draft = draftByAction[action.id];
           const displayCombo = draft ?? effective;
           const hasDraft = typeof draft === 'string' && normalizeCombo(draft) !== normalizeCombo(effective);
+          const isUnassignedDisplay = displayCombo === '' || normalizeCombo(displayCombo) === UNASSIGNED_SHORTCUT;
+          const displayValue = capturingActionId === action.id
+            ? t('settings.openchamber.keyboardShortcuts.field.pressKeys')
+            : isSurfaceSwitch && !isUnassignedDisplay
+              ? `${formatShortcutForDisplay(displayCombo)}${t('settings.openchamber.keyboardShortcuts.action.switch_context_surface.suffix')}`
+              : formatShortcutForDisplay(displayCombo);
 
           return (
             <div key={action.id} className={cn("py-1.5", index > 0 && "border-t border-border/40")}>
@@ -224,7 +263,7 @@ export const KeyboardShortcutsSettings: React.FC = () => {
               >
                 <Input
                   readOnly
-                  value={capturingActionId === action.id ? t('settings.openchamber.keyboardShortcuts.field.pressKeys') : formatShortcutForDisplay(displayCombo)}
+                  value={displayValue}
                   onFocus={() => {
                     setCapturingActionId(action.id);
                     setErrorText('');
@@ -243,7 +282,7 @@ export const KeyboardShortcutsSettings: React.FC = () => {
                       return;
                     }
 
-                    const combo = keyboardEventToCombo(event);
+                    const combo = isSurfaceSwitch ? keyboardEventToPrefixCombo(event) : keyboardEventToCombo(event);
                     if (!combo) {
                       return;
                     }
diff --git a/packages/ui/src/components/session/sidebar/SidebarFooter.tsx b/packages/ui/src/components/session/sidebar/SidebarFooter.tsx
index 228aae8b..befc446d 100644
--- a/packages/ui/src/components/session/sidebar/SidebarFooter.tsx
+++ b/packages/ui/src/components/session/sidebar/SidebarFooter.tsx
@@ -44,7 +44,7 @@ export function SidebarFooter({
           <Tooltip>
             <TooltipTrigger asChild>
               <button type="button" onClick={onOpenShortcuts} className={footerButtonClassName} aria-label={t('sessions.sidebar.footer.actions.shortcuts')}>
-                <Icon name="question" className="h-4.5 w-4.5" />
+                <Icon name="command" className="h-4.5 w-4.5" />
               </button>
             </TooltipTrigger>
             <TooltipContent side="top" sideOffset={4}><p>{t('sessions.sidebar.footer.actions.shortcuts')}</p></TooltipContent>
diff --git a/packages/ui/src/components/ui/HelpDialog.tsx b/packages/ui/src/components/ui/HelpDialog.tsx
index 027e8833..6ed250ea 100644
--- a/packages/ui/src/components/ui/HelpDialog.tsx
+++ b/packages/ui/src/components/ui/HelpDialog.tsx
@@ -175,6 +175,11 @@ export const HelpDialog: React.FC = () => {
           icon: "time",
           keys: '',
         },
+        {
+          keys: [`${mod} + 1...0`],
+          descriptionKey: "helpDialog.item.switchContextSurface",
+          icon: "layout-right",
+        },
       ],
     },
     {
@@ -186,11 +191,6 @@ export const HelpDialog: React.FC = () => {
           icon: "palette",
           keys: '',
         },
-        {
-          keys: [`${mod} + 1...9`],
-          descriptionKey: "helpDialog.item.switchProject",
-          icon: "layout-left",
-        },
         {
           id: 'toggle_services_menu',
           descriptionKey: 'helpDialog.item.toggleServicesMenu',
@@ -218,7 +218,7 @@ export const HelpDialog: React.FC = () => {
       <DialogContent className="max-w-2xl w-[min(42rem,calc(100vw-1.5rem))] max-h-[calc(100dvh-2rem)] flex flex-col overflow-hidden">
         <DialogHeader>
           <DialogTitle className="flex items-center gap-2">
-            <Icon name="settings-3" className="h-5 w-5" />
+            <Icon name="command" className="h-5 w-5" />
             {t('helpDialog.title')}
           </DialogTitle>
           <DialogDescription>
diff --git a/packages/ui/src/hooks/useKeyboardShortcuts.ts b/packages/ui/src/hooks/useKeyboardShortcuts.ts
index 87cabf01..8e3ac00a 100644
--- a/packages/ui/src/hooks/useKeyboardShortcuts.ts
+++ b/packages/ui/src/hooks/useKeyboardShortcuts.ts
@@ -10,10 +10,19 @@ import { createWorktreeSession } from '@/lib/worktreeSessionCreator';
 import { useConfigStore } from '@/stores/useConfigStore';
 import { canUseElectronDesktopIPC, invokeDesktop, isVSCodeRuntime } from '@/lib/desktop';
 import { showOpenCodeStatus } from '@/lib/openCodeStatus';
-import { eventMatchesShortcut, getEffectiveShortcutCombo, normalizeCombo } from '@/lib/shortcuts';
+import {
+  eventMatchesShortcut,
+  eventMatchesShortcutPrefix,
+  getEffectiveShortcutCombo,
+  getEffectiveShortcutPrefix,
+  normalizeCombo,
+} from '@/lib/shortcuts';
+import { getVisibleContextRailSurfaces } from '@/lib/surfaces/registry';
 import { readEmbeddedThemeSearchParams } from '@/contexts/theme-embedded-bootstrap';
 import { useDirectoryStore } from '@/stores/useDirectoryStore';
 import { useProjectsStore } from '@/stores/useProjectsStore';
+import { useFeatureFlagsStore } from '@/stores/useFeatureFlagsStore';
+import { useEffectiveDirectory } from '@/hooks/useEffectiveDirectory';
 import { getCycledPrimaryAgentName } from '@/components/chat/mobileControlsUtils';
 import { focusChatInput } from '@/components/chat/composer/editor/dom';
 import { addSelectionToChat } from '@/lib/addSelectionToChat';
@@ -29,6 +38,7 @@ export const useKeyboardShortcuts = () => {
   const toggleHelpDialog = useUIStore((s) => s.toggleHelpDialog);
   const toggleSidebar = useUIStore((s) => s.toggleSidebar);
   const currentShortcutDirectory = useDirectoryStore((s) => s.currentDirectory);
+  const effectiveDirectory = useEffectiveDirectory();
 
   // The terminal lives in the context panel; these mirror the rail behavior.
   const toggleTerminalSurface = React.useCallback(() => {
@@ -64,6 +74,9 @@ export const useKeyboardShortcuts = () => {
   const abortPrimedUntilRef = React.useRef<number | null>(null);
   const abortPrimedTimeoutRef = React.useRef<ReturnType<typeof setTimeout> | null>(null);
   const themeModeRef = React.useRef(themeMode);
+  // Currently held physical keys (lowercased), used to match chord prefixes
+  // whose primary key must be held while the activating key is pressed.
+  const heldKeysRef = React.useRef<Set<string>>(new Set());
 
   React.useEffect(() => {
     themeModeRef.current = themeMode;
@@ -80,6 +93,7 @@ export const useKeyboardShortcuts = () => {
 
   React.useEffect(() => {
     const combo = (actionId: string) => getEffectiveShortcutCombo(actionId, shortcutOverrides);
+    const switchSurfacePrefix = getEffectiveShortcutPrefix('switch_context_surface', shortcutOverrides);
     const dropdownTargetSelector = [
       '[data-slot="dropdown-menu-content"]',
       '[data-slot="select-content"]',
@@ -448,16 +462,6 @@ export const useKeyboardShortcuts = () => {
         return;
       }
 
-      if (eventMatchesShortcut(e, combo('open_diff_panel'))) {
-        const state = useUIStore.getState();
-        if (state.isMobile || !currentDirectory) {
-          return;
-        }
-        e.preventDefault();
-        state.openContextSurface(normalizeContextPanelDirectoryKey(currentDirectory), 'diff');
-        return;
-      }
-
       if (eventMatchesShortcut(e, combo('toggle_terminal'))) {
         const { isMobile } = useUIStore.getState();
         if (isMobile) {
@@ -478,6 +482,39 @@ export const useKeyboardShortcuts = () => {
         return;
       }
 
+      // Configured prefix + digit (default: Cmd/Ctrl + 1..9, with 0 for the
+      // 10th surface): open/close the matching context panel rail surface. The
+      // digit maps to the currently visible rail order, matching the number
+      // badges shown while holding the modifier. `e.repeat` guard keeps
+      // holding a digit from toggling.
+      const switchSurfaceDigit = e.key.length === 1 && e.key >= '0' && e.key <= '9'
+        ? (e.key === '0' ? 10 : Number(e.key))
+        : null;
+      if (switchSurfaceDigit !== null
+        && !e.repeat
+        && eventMatchesShortcutPrefix(e, switchSurfacePrefix, heldKeysRef.current)) {
+        const state = useUIStore.getState();
+        if (state.isMobile || !effectiveDirectory) {
+          return;
+        }
+        const directory = normalizeContextPanelDirectoryKey(effectiveDirectory);
+        const panelState = state.contextPanelByDirectory[directory];
+        const visibleSurfaces = getVisibleContextRailSurfaces({
+          railOrder: state.contextRailOrder,
+          planModeEnabled: useFeatureFlagsStore.getState().planModeEnabled,
+          isVSCode: isVSCodeRuntime(),
+          screenWidth: window.innerWidth,
+          tabs: panelState?.tabs ?? [],
+        });
+        const target = visibleSurfaces[switchSurfaceDigit - 1];
+        if (!target) {
+          return;
+        }
+        e.preventDefault();
+        state.openContextSurface(directory, target.mode);
+        return;
+      }
+
       // Cmd/Ctrl+Shift+M: Open model selector (same conditions as double-ESC: chat tab, no overlays)
       if (eventMatchesShortcut(e, combo('open_model_selector'))) {
         const {
@@ -618,11 +655,30 @@ export const useKeyboardShortcuts = () => {
 
     };
 
+    // Track held physical keys so chord prefixes (e.g. a configured
+    // `mod+p`) can require their primary key to stay held. Capture phase runs
+    // before handleKeyDown, so the set is current when chord matching runs.
+    const handleKeyHoldDown = (e: KeyboardEvent) => {
+      heldKeysRef.current.add(e.key.toLowerCase());
+    };
+    const handleKeyUp = (e: KeyboardEvent) => {
+      heldKeysRef.current.delete(e.key.toLowerCase());
+    };
+    const handleWindowBlur = () => {
+      heldKeysRef.current.clear();
+    };
+
+    window.addEventListener('keydown', handleKeyHoldDown, true);
+    window.addEventListener('keyup', handleKeyUp, true);
+    window.addEventListener('blur', handleWindowBlur);
     window.addEventListener('keydown', handleTerminalShortcutCapture, true);
     window.addEventListener('keydown', handleEscapeKeyDownCapture, true);
     window.addEventListener('keydown', handleKeyDown);
 
     return () => {
+      window.removeEventListener('keydown', handleKeyHoldDown, true);
+      window.removeEventListener('keyup', handleKeyUp, true);
+      window.removeEventListener('blur', handleWindowBlur);
       window.removeEventListener('keydown', handleTerminalShortcutCapture, true);
       window.removeEventListener('keydown', handleEscapeKeyDownCapture, true);
       window.removeEventListener('keydown', handleKeyDown);
@@ -650,6 +706,7 @@ export const useKeyboardShortcuts = () => {
     resetAbortPriming,
     currentSessionId,
     currentDirectory,
+    effectiveDirectory,
     activeProject?.id,
     activeProject?.path,
     shortcutOverrides,
diff --git a/packages/ui/src/lib/i18n/messages/de.settings.ts b/packages/ui/src/lib/i18n/messages/de.settings.ts
index 94cc8694..104a37d9 100644
--- a/packages/ui/src/lib/i18n/messages/de.settings.ts
+++ b/packages/ui/src/lib/i18n/messages/de.settings.ts
@@ -1043,6 +1043,8 @@ export const settingsDict = {
   'settings.openchamber.keyboardShortcuts.action.toggle_right_sidebar.label': 'Rechte Seitenleiste umschalten',
   'settings.openchamber.keyboardShortcuts.action.open_right_sidebar_git.label': 'Git-Tab der rechten Seitenleiste öffnen',
   'settings.openchamber.keyboardShortcuts.action.open_right_sidebar_files.label': 'Datei-Tab der rechten Seitenleiste öffnen',
+  'settings.openchamber.keyboardShortcuts.action.switch_context_surface.label': 'Kontextpanel-Oberfläche wechseln',
+  'settings.openchamber.keyboardShortcuts.action.switch_context_surface.suffix': ' + 1…0',
   'settings.openchamber.keyboardShortcuts.action.new_chat.label': 'Neue Sitzung',
   'settings.openchamber.keyboardShortcuts.action.new_chat_worktree.label': 'Neuer Worktree-Entwurf',
   'settings.openchamber.keyboardShortcuts.action.new_mini_chat.label': 'Neues Mini-Chat-Fenster',
diff --git a/packages/ui/src/lib/i18n/messages/de.ts b/packages/ui/src/lib/i18n/messages/de.ts
index b6bd1b81..a169280f 100644
--- a/packages/ui/src/lib/i18n/messages/de.ts
+++ b/packages/ui/src/lib/i18n/messages/de.ts
@@ -1558,7 +1558,7 @@ export const dict = {
   'helpDialog.item.toggleTerminalExpanded': 'Terminal erweitert umschalten',
   'helpDialog.item.togglePlanContextPanel': 'Plan-Kontext-Panel umschalten',
   'helpDialog.item.cycleTheme': 'Thema wechseln (Hell → Dunkel → System)',
-  'helpDialog.item.switchProject': 'Projekt wechseln',
+  'helpDialog.item.switchContextSurface': 'Kontextpanel-Oberfläche wechseln (Zahlentaste)',
   'helpDialog.item.toggleServicesMenu': 'Dienstemenü umschalten',
   'helpDialog.item.cycleServicesTab': 'Dienste-Registerkarte durchgehen',
   'helpDialog.item.openSettings': 'Einstellungen öffnen',
diff --git a/packages/ui/src/lib/i18n/messages/en.settings.ts b/packages/ui/src/lib/i18n/messages/en.settings.ts
index 82ef3778..c021f305 100644
--- a/packages/ui/src/lib/i18n/messages/en.settings.ts
+++ b/packages/ui/src/lib/i18n/messages/en.settings.ts
@@ -1108,6 +1108,8 @@ export const settingsDict = {
   'settings.openchamber.keyboardShortcuts.action.toggle_right_sidebar.label': 'Toggle context panel',
   'settings.openchamber.keyboardShortcuts.action.open_right_sidebar_git.label': 'Open Git surface',
   'settings.openchamber.keyboardShortcuts.action.open_right_sidebar_files.label': 'Open Files surface',
+  'settings.openchamber.keyboardShortcuts.action.switch_context_surface.label': 'Switch context panel surface',
+  'settings.openchamber.keyboardShortcuts.action.switch_context_surface.suffix': ' + 1…0',
   'settings.openchamber.keyboardShortcuts.action.new_chat.label': 'New session',
   'settings.openchamber.keyboardShortcuts.action.new_chat_worktree.label': 'New worktree draft',
   'settings.openchamber.keyboardShortcuts.action.new_mini_chat.label': 'New Mini Chat window',
diff --git a/packages/ui/src/lib/i18n/messages/en.ts b/packages/ui/src/lib/i18n/messages/en.ts
index 042c5cf8..6d2e76a5 100644
--- a/packages/ui/src/lib/i18n/messages/en.ts
+++ b/packages/ui/src/lib/i18n/messages/en.ts
@@ -1710,8 +1710,8 @@ export const dict = {
   'helpDialog.item.toggleTerminalDock': 'Toggle Terminal Dock',
   'helpDialog.item.toggleTerminalExpanded': 'Toggle Terminal Expanded',
   'helpDialog.item.togglePlanContextPanel': 'Toggle Plan Context Panel',
+  'helpDialog.item.switchContextSurface': 'Switch Context Panel Surface (number key)',
   'helpDialog.item.cycleTheme': 'Cycle Theme (Light → Dark → System)',
-  'helpDialog.item.switchProject': 'Switch Project',
   'helpDialog.item.toggleServicesMenu': 'Toggle Services Menu',
   'helpDialog.item.cycleServicesTab': 'Cycle Services Tab',
   'helpDialog.item.openSettings': 'Open Settings',
diff --git a/packages/ui/src/lib/i18n/messages/es.settings.ts b/packages/ui/src/lib/i18n/messages/es.settings.ts
index b4613162..74db714b 100644
--- a/packages/ui/src/lib/i18n/messages/es.settings.ts
+++ b/packages/ui/src/lib/i18n/messages/es.settings.ts
@@ -1075,6 +1075,8 @@ export const settingsDict = {
   "settings.openchamber.keyboardShortcuts.action.toggle_right_sidebar.label": 'Alternar panel de contexto',
   "settings.openchamber.keyboardShortcuts.action.open_right_sidebar_git.label": 'Abrir superficie de Git',
   "settings.openchamber.keyboardShortcuts.action.open_right_sidebar_files.label": 'Abrir superficie de archivos',
+  "settings.openchamber.keyboardShortcuts.action.switch_context_surface.label": "Cambiar superficie del panel de contexto",
+  "settings.openchamber.keyboardShortcuts.action.switch_context_surface.suffix": " + 1…0",
   "settings.openchamber.keyboardShortcuts.action.new_chat.label": "Nueva sesión",
   "settings.openchamber.keyboardShortcuts.action.new_chat_worktree.label": "Nuevo borrador de worktree",
   "settings.openchamber.keyboardShortcuts.action.new_mini_chat.label": "Nueva ventana Mini Chat",
diff --git a/packages/ui/src/lib/i18n/messages/es.ts b/packages/ui/src/lib/i18n/messages/es.ts
index 6209796c..18a8b9ed 100644
--- a/packages/ui/src/lib/i18n/messages/es.ts
+++ b/packages/ui/src/lib/i18n/messages/es.ts
@@ -1689,7 +1689,7 @@ export const dict: Record<I18nKey, string> = {
   "helpDialog.item.toggleTerminalExpanded": "Expandir o contraer terminal",
   "helpDialog.item.togglePlanContextPanel": "Alternar panel de contexto del plan",
   "helpDialog.item.cycleTheme": "Cambiar tema (Claro → Oscuro → Sistema)",
-  "helpDialog.item.switchProject": "Cambiar proyecto",
+  "helpDialog.item.switchContextSurface": "Cambiar superficie del panel de contexto (tecla numérica)",
   "helpDialog.item.toggleServicesMenu": "Mostrar u ocultar menú de servicios",
   "helpDialog.item.cycleServicesTab": "Cambiar pestaña de servicios",
   "helpDialog.item.openSettings": "Abrir configuración",
diff --git a/packages/ui/src/lib/i18n/messages/fr.settings.ts b/packages/ui/src/lib/i18n/messages/fr.settings.ts
index 249dfad8..f0c98448 100644
--- a/packages/ui/src/lib/i18n/messages/fr.settings.ts
+++ b/packages/ui/src/lib/i18n/messages/fr.settings.ts
@@ -996,6 +996,8 @@ export const settingsDict = {
   'settings.openchamber.keyboardShortcuts.action.toggle_right_sidebar.label': 'Afficher/masquer le panneau de contexte',
   'settings.openchamber.keyboardShortcuts.action.open_right_sidebar_git.label': 'Ouvrir la surface Git',
   'settings.openchamber.keyboardShortcuts.action.open_right_sidebar_files.label': 'Ouvrir la surface Fichiers',
+  'settings.openchamber.keyboardShortcuts.action.switch_context_surface.label': 'Basculer la surface du panneau contextuel',
+  'settings.openchamber.keyboardShortcuts.action.switch_context_surface.suffix': ' + 1…0',
   'settings.openchamber.keyboardShortcuts.action.new_chat.label': 'Nouvelle session',
   'settings.openchamber.keyboardShortcuts.action.new_chat_worktree.label': 'Nouvelle ébauche d\'worktree',
   'settings.openchamber.keyboardShortcuts.action.new_mini_chat.label': 'Nouvelle fenêtre de mini-chat',
diff --git a/packages/ui/src/lib/i18n/messages/fr.ts b/packages/ui/src/lib/i18n/messages/fr.ts
index 09357712..a387f1c7 100644
--- a/packages/ui/src/lib/i18n/messages/fr.ts
+++ b/packages/ui/src/lib/i18n/messages/fr.ts
@@ -1524,7 +1524,7 @@ export const dict = {
   'helpDialog.item.toggleTerminalExpanded': 'Terminal à bascule étendu',
   'helpDialog.item.togglePlanContextPanel': 'Toggle Panneau contextuel du plan',
   'helpDialog.item.cycleTheme': 'Basculer le thème (clair → sombre → système)',
-  'helpDialog.item.switchProject': 'Changer de projet',
+  'helpDialog.item.switchContextSurface': 'Basculer la surface du panneau contextuel (touche numérique)',
   'helpDialog.item.toggleServicesMenu': 'Basculer le menu des services',
   'helpDialog.item.cycleServicesTab': 'Onglet Services de vélo',
   'helpDialog.item.openSettings': 'Ouvrir les paramètres',
diff --git a/packages/ui/src/lib/i18n/messages/ja.settings.ts b/packages/ui/src/lib/i18n/messages/ja.settings.ts
index f2c58bdd..0c82f734 100644
--- a/packages/ui/src/lib/i18n/messages/ja.settings.ts
+++ b/packages/ui/src/lib/i18n/messages/ja.settings.ts
@@ -1108,6 +1108,8 @@ export const settingsDict = {
   'settings.openchamber.keyboardShortcuts.action.toggle_right_sidebar.label': 'コンテキストパネルの表示切替',
   'settings.openchamber.keyboardShortcuts.action.open_right_sidebar_git.label': 'Git サーフェスを開く',
   'settings.openchamber.keyboardShortcuts.action.open_right_sidebar_files.label': 'ファイルサーフェスを開く',
+  'settings.openchamber.keyboardShortcuts.action.switch_context_surface.label': 'コンテキストパネルのサーフェスを切り替え',
+  'settings.openchamber.keyboardShortcuts.action.switch_context_surface.suffix': ' + 1…0',
   'settings.openchamber.keyboardShortcuts.action.new_chat.label': '新しい Session',
   'settings.openchamber.keyboardShortcuts.action.new_chat_worktree.label': '新しい Worktree 下書き',
   'settings.openchamber.keyboardShortcuts.action.new_mini_chat.label': '新しいミニチャットウィンドウ',
diff --git a/packages/ui/src/lib/i18n/messages/ja.ts b/packages/ui/src/lib/i18n/messages/ja.ts
index f8aab496..68a4fb7a 100644
--- a/packages/ui/src/lib/i18n/messages/ja.ts
+++ b/packages/ui/src/lib/i18n/messages/ja.ts
@@ -1707,7 +1707,7 @@ export const dict: Record<I18nKey, string> = {
   'helpDialog.item.toggleTerminalExpanded': 'ターミナル展開の切り替え',
   'helpDialog.item.togglePlanContextPanel': '計画コンテキストパネルの切り替え',
   'helpDialog.item.cycleTheme': 'テーマ切り替え（ライト→ダーク→システム）',
-  'helpDialog.item.switchProject': 'プロジェクトを切り替え',
+  'helpDialog.item.switchContextSurface': 'コンテキストパネルのサーフェスを切り替え（数字キー）',
   'helpDialog.item.toggleServicesMenu': 'サービスの切り替え',
   'helpDialog.item.cycleServicesTab': 'サービス変数の切り替え',
   'helpDialog.item.openSettings': '設定を開く',
diff --git a/packages/ui/src/lib/i18n/messages/ko.settings.ts b/packages/ui/src/lib/i18n/messages/ko.settings.ts
index 0f9b0aba..aa53cbfd 100644
--- a/packages/ui/src/lib/i18n/messages/ko.settings.ts
+++ b/packages/ui/src/lib/i18n/messages/ko.settings.ts
@@ -1075,6 +1075,8 @@ export const settingsDict = {
   'settings.openchamber.keyboardShortcuts.action.toggle_right_sidebar.label': '컨텍스트 패널 표시 전환',
   'settings.openchamber.keyboardShortcuts.action.open_right_sidebar_git.label': 'Git 서피스 열기',
   'settings.openchamber.keyboardShortcuts.action.open_right_sidebar_files.label': '파일 서피스 열기',
+  'settings.openchamber.keyboardShortcuts.action.switch_context_surface.label': '컨텍스트 패널 서피스 전환',
+  'settings.openchamber.keyboardShortcuts.action.switch_context_surface.suffix': ' + 1…0',
   'settings.openchamber.keyboardShortcuts.action.new_chat.label': '새 세션',
   'settings.openchamber.keyboardShortcuts.action.new_chat_worktree.label': '새 worktree 초안',
   'settings.openchamber.keyboardShortcuts.action.new_mini_chat.label': '새 Mini Chat 창',
diff --git a/packages/ui/src/lib/i18n/messages/ko.ts b/packages/ui/src/lib/i18n/messages/ko.ts
index ee0e0464..03532bc5 100644
--- a/packages/ui/src/lib/i18n/messages/ko.ts
+++ b/packages/ui/src/lib/i18n/messages/ko.ts
@@ -1713,7 +1713,7 @@ export const dict: Record<I18nKey, string> = {
   'helpDialog.item.toggleTerminalExpanded': '터미널 펼치기/접기',
   'helpDialog.item.togglePlanContextPanel': '플랜 컨텍스트 패널 전환',
   'helpDialog.item.cycleTheme': '테마 순환(라이트 → 다크 → 시스템)',
-  'helpDialog.item.switchProject': '프로젝트 전환',
+  'helpDialog.item.switchContextSurface': '컨텍스트 패널 서피스 전환(숫자 키)',
   'helpDialog.item.toggleServicesMenu': '서비스 메뉴 전환',
   'helpDialog.item.cycleServicesTab': '서비스 탭 순환',
   'helpDialog.item.openSettings': '설정 열기',
diff --git a/packages/ui/src/lib/i18n/messages/pl.settings.ts b/packages/ui/src/lib/i18n/messages/pl.settings.ts
index 89bafd5b..aa3af5d6 100644
--- a/packages/ui/src/lib/i18n/messages/pl.settings.ts
+++ b/packages/ui/src/lib/i18n/messages/pl.settings.ts
@@ -820,6 +820,8 @@ export const settingsDict = {
   'settings.openchamber.keyboardShortcuts.action.open_go_to_line.label': 'Przejdź do linii (edytor plików)',
   'settings.openchamber.keyboardShortcuts.action.open_help.label': 'Otwórz skróty klawiszowe',
   'settings.openchamber.keyboardShortcuts.action.open_right_sidebar_files.label': 'Otwórz powierzchnię plików',
+  'settings.openchamber.keyboardShortcuts.action.switch_context_surface.label': 'Przełącz powierzchnię panelu kontekstu',
+  'settings.openchamber.keyboardShortcuts.action.switch_context_surface.suffix': ' + 1…0',
   'settings.openchamber.keyboardShortcuts.action.open_right_sidebar_git.label': 'Otwórz powierzchnię Git',
   'settings.openchamber.keyboardShortcuts.action.open_settings.label': 'Otwórz ustawienia',
   'settings.openchamber.keyboardShortcuts.action.toggle_context_plan.label': 'Przełącz panel kontekstu planu',
diff --git a/packages/ui/src/lib/i18n/messages/pl.ts b/packages/ui/src/lib/i18n/messages/pl.ts
index 120967fd..245cbc5f 100644
--- a/packages/ui/src/lib/i18n/messages/pl.ts
+++ b/packages/ui/src/lib/i18n/messages/pl.ts
@@ -2333,7 +2333,7 @@ export const dict: Record<I18nKey, string> = {
   'helpDialog.item.openRightSidebarGitTab': 'Otwórz powierzchnię Git',
   'helpDialog.item.openSettings': 'Otwórz ustawienia',
   'helpDialog.item.showKeyboardShortcuts': 'Pokaż skróty klawiaturowe (to okno)',
-  'helpDialog.item.switchProject': 'Przełącz projekt',
+  'helpDialog.item.switchContextSurface': 'Przełącz powierzchnię panelu kontekstu (klawisz liczbowy)',
   'helpDialog.item.togglePlanContextPanel': 'Przełącz panel kontekstu planu',
   'helpDialog.item.toggleRightSidebar': 'Przełącz panel kontekstu',
   'helpDialog.item.toggleServicesMenu': 'Przełącz menu usług',
diff --git a/packages/ui/src/lib/i18n/messages/pt-BR.settings.ts b/packages/ui/src/lib/i18n/messages/pt-BR.settings.ts
index 73386454..c321f233 100644
--- a/packages/ui/src/lib/i18n/messages/pt-BR.settings.ts
+++ b/packages/ui/src/lib/i18n/messages/pt-BR.settings.ts
@@ -1075,6 +1075,8 @@ export const settingsDict = {
   "settings.openchamber.keyboardShortcuts.action.toggle_right_sidebar.label": 'Alternar painel de contexto',
   "settings.openchamber.keyboardShortcuts.action.open_right_sidebar_git.label": 'Abrir superfície do Git',
   "settings.openchamber.keyboardShortcuts.action.open_right_sidebar_files.label": 'Abrir superfície de arquivos',
+  "settings.openchamber.keyboardShortcuts.action.switch_context_surface.label": "Alternar superfície do painel de contexto",
+  "settings.openchamber.keyboardShortcuts.action.switch_context_surface.suffix": " + 1…0",
   "settings.openchamber.keyboardShortcuts.action.new_chat.label": "Nova sessão",
   "settings.openchamber.keyboardShortcuts.action.new_chat_worktree.label": "Novo rascunho de worktree",
   "settings.openchamber.keyboardShortcuts.action.new_mini_chat.label": "Nova janela Mini Chat",
diff --git a/packages/ui/src/lib/i18n/messages/pt-BR.ts b/packages/ui/src/lib/i18n/messages/pt-BR.ts
index c6fc84f4..42098a94 100644
--- a/packages/ui/src/lib/i18n/messages/pt-BR.ts
+++ b/packages/ui/src/lib/i18n/messages/pt-BR.ts
@@ -1689,7 +1689,7 @@ export const dict: Record<I18nKey, string> = {
   "helpDialog.item.toggleTerminalExpanded": "Expandir ou recolher o terminal",
   "helpDialog.item.togglePlanContextPanel": "Alternar painel de contexto do plano",
   "helpDialog.item.cycleTheme": "Alternar tema (Claro → Escuro → Sistema)",
-  "helpDialog.item.switchProject": "Alternar projeto",
+  "helpDialog.item.switchContextSurface": "Alternar superfície do painel de contexto (tecla numérica)",
   "helpDialog.item.toggleServicesMenu": "Mostrar ou ocultar menu de serviços",
   "helpDialog.item.cycleServicesTab": "Alternar aba de serviços",
   "helpDialog.item.openSettings": "Abrir configurações",
diff --git a/packages/ui/src/lib/i18n/messages/uk.settings.ts b/packages/ui/src/lib/i18n/messages/uk.settings.ts
index 42d29d22..c5afd784 100644
--- a/packages/ui/src/lib/i18n/messages/uk.settings.ts
+++ b/packages/ui/src/lib/i18n/messages/uk.settings.ts
@@ -1075,6 +1075,8 @@ export const settingsDict = {
   "settings.openchamber.keyboardShortcuts.action.toggle_right_sidebar.label": 'Перемкнути контекстну панель',
   "settings.openchamber.keyboardShortcuts.action.open_right_sidebar_git.label": 'Відкрити поверхню Git',
   "settings.openchamber.keyboardShortcuts.action.open_right_sidebar_files.label": 'Відкрити поверхню файлів',
+  "settings.openchamber.keyboardShortcuts.action.switch_context_surface.label": "Перемкнути поверхню панелі контексту",
+  "settings.openchamber.keyboardShortcuts.action.switch_context_surface.suffix": " + 1…0",
   "settings.openchamber.keyboardShortcuts.action.new_chat.label": "Нова сесія",
   "settings.openchamber.keyboardShortcuts.action.new_chat_worktree.label": "Нова чернетка worktree",
   "settings.openchamber.keyboardShortcuts.action.new_mini_chat.label": "Нове вікно Mini Chat",
diff --git a/packages/ui/src/lib/i18n/messages/uk.ts b/packages/ui/src/lib/i18n/messages/uk.ts
index 803b791b..1143d4c0 100644
--- a/packages/ui/src/lib/i18n/messages/uk.ts
+++ b/packages/ui/src/lib/i18n/messages/uk.ts
@@ -1689,7 +1689,7 @@ export const dict: Record<I18nKey, string> = {
   "helpDialog.item.toggleTerminalExpanded": "Розгорнути або згорнути термінал",
   "helpDialog.item.togglePlanContextPanel": "Перемкнути панель контексту плану",
   "helpDialog.item.cycleTheme": "Перемкнути тему (Світла → Темна → Системна)",
-  "helpDialog.item.switchProject": "Перемкнути проєкт",
+  "helpDialog.item.switchContextSurface": "Перемкнути поверхню панелі контексту (цифрова клавіша)",
   "helpDialog.item.toggleServicesMenu": "Перемкнути меню сервісів",
   "helpDialog.item.cycleServicesTab": "Перемкнути вкладку сервісів",
   "helpDialog.item.openSettings": "Відкрити налаштування",
diff --git a/packages/ui/src/lib/i18n/messages/zh-CN.settings.ts b/packages/ui/src/lib/i18n/messages/zh-CN.settings.ts
index 36f85a43..2d111132 100644
--- a/packages/ui/src/lib/i18n/messages/zh-CN.settings.ts
+++ b/packages/ui/src/lib/i18n/messages/zh-CN.settings.ts
@@ -1075,6 +1075,8 @@ export const settingsDict = {
   'settings.openchamber.keyboardShortcuts.action.toggle_right_sidebar.label': '切换上下文面板',
   'settings.openchamber.keyboardShortcuts.action.open_right_sidebar_git.label': '打开 Git 界面',
   'settings.openchamber.keyboardShortcuts.action.open_right_sidebar_files.label': '打开文件界面',
+  'settings.openchamber.keyboardShortcuts.action.switch_context_surface.label': '切换上下文面板界面',
+  'settings.openchamber.keyboardShortcuts.action.switch_context_surface.suffix': ' + 1…0',
   'settings.openchamber.keyboardShortcuts.action.new_chat.label': '新建会话',
   'settings.openchamber.keyboardShortcuts.action.new_chat_worktree.label': '新建工作树草稿',
   'settings.openchamber.keyboardShortcuts.action.new_mini_chat.label': '新建 Mini Chat 窗口',
diff --git a/packages/ui/src/lib/i18n/messages/zh-CN.ts b/packages/ui/src/lib/i18n/messages/zh-CN.ts
index db955a7e..7e9fa6c9 100644
--- a/packages/ui/src/lib/i18n/messages/zh-CN.ts
+++ b/packages/ui/src/lib/i18n/messages/zh-CN.ts
@@ -1677,7 +1677,7 @@ export const dict: Record<I18nKey, string> = {
   'helpDialog.item.toggleTerminalExpanded': '切换终端展开状态',
   'helpDialog.item.togglePlanContextPanel': '切换计划上下文面板',
   'helpDialog.item.cycleTheme': '循环切换主题（浅色 → 深色 → 跟随系统）',
-  'helpDialog.item.switchProject': '切换项目',
+  'helpDialog.item.switchContextSurface': '切换上下文面板界面（数字键）',
   'helpDialog.item.toggleServicesMenu': '切换服务菜单',
   'helpDialog.item.cycleServicesTab': '循环服务标签',
   'helpDialog.item.openSettings': '打开设置',
diff --git a/packages/ui/src/lib/i18n/messages/zh-TW.settings.ts b/packages/ui/src/lib/i18n/messages/zh-TW.settings.ts
index 892dab37..4118c83d 100644
--- a/packages/ui/src/lib/i18n/messages/zh-TW.settings.ts
+++ b/packages/ui/src/lib/i18n/messages/zh-TW.settings.ts
@@ -982,6 +982,8 @@
   'settings.openchamber.keyboardShortcuts.action.toggle_right_sidebar.label': '切換上下文面板',
   'settings.openchamber.keyboardShortcuts.action.open_right_sidebar_git.label': '開啟 Git 介面',
   'settings.openchamber.keyboardShortcuts.action.open_right_sidebar_files.label': '開啟檔案介面',
+  'settings.openchamber.keyboardShortcuts.action.switch_context_surface.label': '切換上下文面板介面',
+  'settings.openchamber.keyboardShortcuts.action.switch_context_surface.suffix': ' + 1…0',
   'settings.openchamber.keyboardShortcuts.action.new_chat.label': '新建工作階段',
   'settings.openchamber.keyboardShortcuts.action.new_chat_worktree.label': '新增 worktree 草稿',
   'settings.openchamber.keyboardShortcuts.action.new_mini_chat.label': '新建 Mini Chat 視窗',
diff --git a/packages/ui/src/lib/i18n/messages/zh-TW.ts b/packages/ui/src/lib/i18n/messages/zh-TW.ts
index 13cbd616..35e3389d 100644
--- a/packages/ui/src/lib/i18n/messages/zh-TW.ts
+++ b/packages/ui/src/lib/i18n/messages/zh-TW.ts
@@ -1681,7 +1681,7 @@ export const dict: Record<I18nKey, string> = {
   'helpDialog.item.toggleTerminalExpanded': '切換終端機展開狀態',
   'helpDialog.item.togglePlanContextPanel': '切換計畫上下文面板',
   'helpDialog.item.cycleTheme': '循環切換主題（淺色 → 深色 → 跟隨系統）',
-  'helpDialog.item.switchProject': '切換專案',
+  'helpDialog.item.switchContextSurface': '切換上下文面板介面（數字鍵）',
   'helpDialog.item.toggleServicesMenu': '切換服務選單',
   'helpDialog.item.cycleServicesTab': '循環服務標籤',
   'helpDialog.item.openSettings': '開啟設定',
diff --git a/packages/ui/src/lib/shortcuts.test.ts b/packages/ui/src/lib/shortcuts.test.ts
new file mode 100644
index 00000000..593ea714
--- /dev/null
+++ b/packages/ui/src/lib/shortcuts.test.ts
@@ -0,0 +1,80 @@
+import { describe, expect, test } from 'bun:test';
+
+import {
+  eventMatchesShortcutPrefix,
+  getEffectiveShortcutPrefix,
+  isShortcutPrefixHeld,
+  UNASSIGNED_SHORTCUT,
+} from './shortcuts';
+
+describe('getEffectiveShortcutPrefix', () => {
+  test('falls back to the action default (bare mod) when unset', () => {
+    expect(getEffectiveShortcutPrefix('switch_context_surface', {})).toBe('mod');
+  });
+
+  test('honors modifier + key overrides', () => {
+    expect(getEffectiveShortcutPrefix('switch_context_surface', { switch_context_surface: 'mod+p' })).toBe('mod+p');
+  });
+
+  test('honors modifier-only overrides', () => {
+    expect(getEffectiveShortcutPrefix('switch_context_surface', { switch_context_surface: 'shift' })).toBe('shift');
+  });
+
+  test('returns UNASSIGNED for an explicit unassignment', () => {
+    expect(
+      getEffectiveShortcutPrefix('switch_context_surface', { switch_context_surface: UNASSIGNED_SHORTCUT }),
+    ).toBe(UNASSIGNED_SHORTCUT);
+  });
+
+  test('returns empty string for an unknown action', () => {
+    expect(getEffectiveShortcutPrefix('does_not_exist', {})).toBe('');
+  });
+});
+
+describe('isShortcutPrefixHeld', () => {
+  test('false for an unassigned prefix', () => {
+    expect(isShortcutPrefixHeld(UNASSIGNED_SHORTCUT, new Set(['control']))).toBe(false);
+  });
+
+  test('requires the prefix primary key to be held', () => {
+    expect(isShortcutPrefixHeld('mod+p', new Set(['control']))).toBe(false);
+    expect(isShortcutPrefixHeld('mod+p', new Set(['control', 'p']))).toBe(true);
+  });
+
+  test('requires every prefix modifier to be held', () => {
+    expect(isShortcutPrefixHeld('mod+shift', new Set(['control']))).toBe(false);
+    expect(isShortcutPrefixHeld('mod+shift', new Set(['control', 'shift']))).toBe(true);
+  });
+});
+
+const keydown = (key: string, mods: { meta?: boolean; ctrl?: boolean; shift?: boolean; alt?: boolean }): KeyboardEvent =>
+  ({
+    key,
+    metaKey: mods.meta ?? false,
+    ctrlKey: mods.ctrl ?? false,
+    shiftKey: mods.shift ?? false,
+    altKey: mods.alt ?? false,
+  }) as KeyboardEvent;
+
+describe('eventMatchesShortcutPrefix', () => {
+  test('matches a bare mod prefix when the primary modifier is held', () => {
+    expect(eventMatchesShortcutPrefix(keydown('1', { ctrl: true }), 'mod')).toBe(true);
+  });
+
+  test('rejects a bare mod prefix without the primary modifier', () => {
+    expect(eventMatchesShortcutPrefix(keydown('1', {}), 'mod')).toBe(false);
+  });
+
+  test('rejects when the event carries modifiers the prefix does not expect', () => {
+    expect(eventMatchesShortcutPrefix(keydown('1', { ctrl: true, shift: true }), 'mod')).toBe(false);
+  });
+
+  test('requires the prefix primary key to be held at match time', () => {
+    expect(eventMatchesShortcutPrefix(keydown('1', { ctrl: true }), 'mod+p', new Set(['control']))).toBe(false);
+    expect(eventMatchesShortcutPrefix(keydown('1', { ctrl: true }), 'mod+p', new Set(['control', 'p']))).toBe(true);
+  });
+
+  test('false for an unassigned prefix', () => {
+    expect(eventMatchesShortcutPrefix(keydown('1', { ctrl: true }), UNASSIGNED_SHORTCUT)).toBe(false);
+  });
+});
diff --git a/packages/ui/src/lib/shortcuts.ts b/packages/ui/src/lib/shortcuts.ts
index 6afb4656..4398aca5 100644
--- a/packages/ui/src/lib/shortcuts.ts
+++ b/packages/ui/src/lib/shortcuts.ts
@@ -39,6 +39,17 @@ const DISPLAY_LABEL_MAP: Record<ShortcutModifier, string> = {
   'ctrl': '⌃',
 };
 
+// Physical `event.key` values (lowercased) that satisfy each modifier while a
+// chord is being held. `mod` maps to the platform primary key; on web macOS it
+// accepts either Meta or Ctrl, matching eventMatchesShortcut.
+const MODIFIER_KEY_ALIASES: Record<ShortcutModifier, readonly string[]> = {
+  'mod': isMacOS() && isDesktopShell() ? ['meta'] : isMacOS() ? ['meta', 'control'] : ['control'],
+  'shift': ['shift'],
+  'alt': ['alt'],
+  'option': ['alt'],
+  'ctrl': ['control'],
+};
+
 const KEY_LABEL_MAP: Record<string, string> = {
   'comma': ',',
   'period': '.',
@@ -207,6 +218,13 @@ const SHORTCUT_ACTIONS: ReadonlyArray<ShortcutAction> = [
     description: 'Open right sidebar and select Files',
     customizable: true,
   },
+  {
+    id: 'switch_context_surface',
+    defaultCombo: 'mod',
+    label: 'Switch context panel surface',
+    description: 'Hold the modifier and press a number to open or close the matching rail icon',
+    customizable: true,
+  },
   {
     id: 'new_chat',
     defaultCombo: 'mod+n',
@@ -240,24 +258,6 @@ const SHORTCUT_ACTIONS: ReadonlyArray<ShortcutAction> = [
     label: 'Clear input',
     description: 'Clear the input field',
   },
-  {
-    id: 'open_diff_panel',
-    defaultCombo: 'mod+2',
-    label: 'Open diff panel',
-    description: 'Switch to the diff panel',
-  },
-  {
-    id: 'open_terminal_panel',
-    defaultCombo: 'mod+3',
-    label: 'Open terminal panel',
-    description: 'Switch to the terminal panel',
-  },
-  {
-    id: 'open_git_panel',
-    defaultCombo: 'mod+4',
-    label: 'Open git panel',
-    description: 'Switch to the git panel',
-  },
   {
     id: 'open_help',
     defaultCombo: 'mod+.',
@@ -347,60 +347,6 @@ const SHORTCUT_ACTIONS: ReadonlyArray<ShortcutAction> = [
     label: 'Abort active run',
     description: 'Abort the currently running task (double press)',
   },
-  {
-    id: 'switch_tab_1',
-    defaultCombo: 'mod+1',
-    label: 'Switch to tab 1',
-    description: 'Switch to the first tab or project',
-  },
-  {
-    id: 'switch_tab_2',
-    defaultCombo: 'mod+2',
-    label: 'Switch to tab 2',
-    description: 'Switch to the second tab or project',
-  },
-  {
-    id: 'switch_tab_3',
-    defaultCombo: 'mod+3',
-    label: 'Switch to tab 3',
-    description: 'Switch to the third tab or project',
-  },
-  {
-    id: 'switch_tab_4',
-    defaultCombo: 'mod+4',
-    label: 'Switch to tab 4',
-    description: 'Switch to the fourth tab or project',
-  },
-  {
-    id: 'switch_tab_5',
-    defaultCombo: 'mod+5',
-    label: 'Switch to tab 5',
-    description: 'Switch to the fifth tab or project',
-  },
-  {
-    id: 'switch_tab_6',
-    defaultCombo: 'mod+6',
-    label: 'Switch to tab 6',
-    description: 'Switch to the sixth tab or project',
-  },
-  {
-    id: 'switch_tab_7',
-    defaultCombo: 'mod+7',
-    label: 'Switch to tab 7',
-    description: 'Switch to the seventh tab or project',
-  },
-  {
-    id: 'switch_tab_8',
-    defaultCombo: 'mod+8',
-    label: 'Switch to tab 8',
-    description: 'Switch to the eighth tab or project',
-  },
-  {
-    id: 'switch_tab_9',
-    defaultCombo: 'mod+9',
-    label: 'Switch to tab 9',
-    description: 'Switch to the ninth tab or project',
-  },
 ] as const;
 
 export function normalizeCombo(combo: ShortcutCombo): ShortcutCombo {
@@ -610,3 +556,126 @@ export function eventMatchesShortcut(
 export function getModifierLabel(): string {
   return isMacOS() && isDesktopShell() ? '⌘' : 'Ctrl';
 }
+
+/**
+ * Resolves the configurable prefix for chord-style shortcuts such as
+ * "switch context panel surface", where a trailing digit key completes the
+ * combo. Unlike getEffectiveShortcutCombo, modifier-only overrides (e.g. the
+ * bare `mod` primary key) are honored so the prefix can omit a primary key.
+ * Returns UNASSIGNED_SHORTCUT when the user explicitly unassigned the prefix.
+ */
+export function getEffectiveShortcutPrefix(
+  actionId: string,
+  overrides?: Record<string, ShortcutCombo>,
+): ShortcutCombo {
+  const action = getShortcutAction(actionId);
+  if (!action) {
+    return '';
+  }
+
+  const override = overrides?.[actionId];
+  if (typeof override === 'string' && override.trim() !== '') {
+    const normalized = normalizeCombo(override);
+    if (normalized === UNASSIGNED_SHORTCUT) {
+      return UNASSIGNED_SHORTCUT;
+    }
+    if (normalized) {
+      const parsed = parseShortcut(normalized);
+      if (parsed.modifiers.size > 0 || parsed.key) {
+        return normalized;
+      }
+    }
+  }
+
+  return action.defaultCombo;
+}
+
+/**
+ * True when the physical keys required to "arm" a prefix combo are currently
+ * held. For modifiers with multiple aliases (e.g. `mod` on web macOS), at
+ * least one alias must be held.
+ */
+export function isShortcutPrefixHeld(prefixCombo: ShortcutCombo, heldKeys: ReadonlySet<string>): boolean {
+  if (isUnassignedShortcut(prefixCombo)) {
+    return false;
+  }
+
+  const parsed = parseShortcut(prefixCombo);
+
+  for (const modifier of parsed.modifiers) {
+    const aliases = MODIFIER_KEY_ALIASES[modifier];
+    if (!aliases.some((alias) => heldKeys.has(alias))) {
+      return false;
+    }
+  }
+
+  if (parsed.key && !heldKeys.has(parsed.key.toLowerCase())) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Matches an activating keydown (the caller checks the event's own key, e.g. a
+ * digit) against a chord prefix: the event's modifier state must match the
+ * prefix's modifiers, and when the prefix has a primary key that key must
+ * currently be held.
+ */
+export function eventMatchesShortcutPrefix(
+  event: KeyboardEvent | React.KeyboardEvent,
+  prefixCombo: ShortcutCombo,
+  heldKeys?: ReadonlySet<string>,
+): boolean {
+  if (isUnassignedShortcut(prefixCombo)) {
+    return false;
+  }
+
+  const parsed = parseShortcut(prefixCombo);
+
+  const expectedMod = parsed.modifiers.has('mod');
+  const expectedShift = parsed.modifiers.has('shift');
+  const expectedAlt = parsed.modifiers.has('alt');
+  const expectedCtrl = parsed.modifiers.has('ctrl');
+  const isDesktopMac = isMacOS() && isDesktopShell();
+  const isMac = isMacOS();
+
+  const modMatches = isDesktopMac
+    ? event.metaKey
+    : isMac
+      ? (event.metaKey || event.ctrlKey)
+      : event.ctrlKey;
+
+  if (expectedMod && !modMatches) {
+    return false;
+  }
+
+  if (!expectedMod && event.metaKey) {
+    return false;
+  }
+
+  if (expectedShift !== event.shiftKey) {
+    return false;
+  }
+
+  if (expectedAlt !== event.altKey) {
+    return false;
+  }
+
+  if (expectedCtrl) {
+    if (!event.ctrlKey) {
+      return false;
+    }
+  } else {
+    const ctrlUsedAsMod = expectedMod && !isDesktopMac && event.ctrlKey;
+    if (event.ctrlKey && !ctrlUsedAsMod) {
+      return false;
+    }
+  }
+
+  if (parsed.key && (!heldKeys || !heldKeys.has(parsed.key.toLowerCase()))) {
+    return false;
+  }
+
+  return true;
+}
diff --git a/packages/ui/src/lib/surfaces/DOCUMENTATION.md b/packages/ui/src/lib/surfaces/DOCUMENTATION.md
index 278f2952..4c5fb57f 100644
--- a/packages/ui/src/lib/surfaces/DOCUMENTATION.md
+++ b/packages/ui/src/lib/surfaces/DOCUMENTATION.md
@@ -20,6 +20,13 @@ edge (`components/layout/ContextPanelRail.tsx`) and rendered by
 - Rail order is user-reorderable and persisted globally in
   `useUIStore.contextRailOrder`; `sortContextSurfaces` applies it on top of the
   registry's default order and appends any missing surfaces.
+- `getVisibleContextRailSurfaces` is the single visibility filter shared by the
+  rail and the global surface-switch shortcut (`switch_context_surface` in
+  `lib/shortcuts.ts`): it drops the plan surface unless plan mode is enabled,
+  drops the walkthrough on VS Code and below `WALKTHROUGH_MIN_WIDTH`, and hides
+  `has-content` surfaces until a tab of their mode exists. Both consumers use
+  it so the digit shown on a rail badge always maps to the same surface the
+  shortcut opens.
 
 ## Adding a surface
 
diff --git a/packages/ui/src/lib/surfaces/registry.test.ts b/packages/ui/src/lib/surfaces/registry.test.ts
new file mode 100644
index 00000000..764ad258
--- /dev/null
+++ b/packages/ui/src/lib/surfaces/registry.test.ts
@@ -0,0 +1,53 @@
+import { describe, expect, test } from 'bun:test';
+
+import {
+  CONTEXT_SURFACES,
+  getVisibleContextRailSurfaces,
+  WALKTHROUGH_MIN_WIDTH,
+} from './registry';
+
+const baseOptions = {
+  railOrder: [],
+  planModeEnabled: true,
+  isVSCode: false,
+  screenWidth: 1200,
+  tabs: [],
+} as const;
+
+describe('getVisibleContextRailSurfaces', () => {
+  test('hides the plan surface while plan mode is disabled', () => {
+    const surfaces = getVisibleContextRailSurfaces({ ...baseOptions, planModeEnabled: false });
+    expect(surfaces.some((surface) => surface.id === 'plan')).toBe(false);
+    expect(surfaces.some((surface) => surface.id === 'context')).toBe(true);
+  });
+
+  test('shows the plan surface while plan mode is enabled', () => {
+    const surfaces = getVisibleContextRailSurfaces({ ...baseOptions, planModeEnabled: true });
+    expect(surfaces.some((surface) => surface.id === 'plan')).toBe(true);
+  });
+
+  test('hides the walkthrough on VS Code and below the min width', () => {
+    expect(getVisibleContextRailSurfaces({ ...baseOptions, isVSCode: true }).some((s) => s.id === 'walkthrough')).toBe(false);
+    expect(
+      getVisibleContextRailSurfaces({ ...baseOptions, screenWidth: WALKTHROUGH_MIN_WIDTH - 1 }).some((s) => s.id === 'walkthrough'),
+    ).toBe(false);
+    expect(
+      getVisibleContextRailSurfaces({ ...baseOptions, screenWidth: WALKTHROUGH_MIN_WIDTH }).some((s) => s.id === 'walkthrough'),
+    ).toBe(true);
+  });
+
+  test('hides content-driven surfaces until a matching tab exists', () => {
+    const preview = CONTEXT_SURFACES.find((surface) => surface.id === 'preview');
+    if (!preview) {
+      throw new Error('preview surface missing from registry');
+    }
+    expect(preview.availability).toBe('has-content');
+    expect(getVisibleContextRailSurfaces(baseOptions).some((s) => s.id === 'preview')).toBe(false);
+    expect(getVisibleContextRailSurfaces({ ...baseOptions, tabs: [{ mode: preview.mode }] }).some((s) => s.id === 'preview')).toBe(true);
+  });
+
+  test('respects the persisted user rail order', () => {
+    const surfaces = getVisibleContextRailSurfaces({ ...baseOptions, railOrder: ['git', 'context'] });
+    expect(surfaces.slice(0, 2).map((surface) => surface.id)).toEqual(['git', 'context']);
+  });
+});
diff --git a/packages/ui/src/lib/surfaces/registry.ts b/packages/ui/src/lib/surfaces/registry.ts
index 0be406bb..87ffe08a 100644
--- a/packages/ui/src/lib/surfaces/registry.ts
+++ b/packages/ui/src/lib/surfaces/registry.ts
@@ -152,6 +152,10 @@ export const CONTEXT_SURFACES: readonly ContextSurfaceDescriptor[] = [
 const SURFACE_BY_ID = new Map(CONTEXT_SURFACES.map((surface) => [surface.id, surface]));
 const FRACTION_BY_MODE = new Map(CONTEXT_SURFACES.map((surface) => [surface.mode, surface.defaultWidthFraction]));
 
+// Tablet width and up: below this the walkthrough cannot show a stop and its
+// code side by side, which is the whole point of the surface.
+export const WALKTHROUGH_MIN_WIDTH = 768;
+
 export const getContextSurfaceWidthFraction = (mode: ContextPanelMode): number => {
   return FRACTION_BY_MODE.get(mode) ?? 1 / 2;
 };
@@ -187,3 +191,36 @@ export const sortContextSurfaces = (railOrder: readonly string[]): ContextSurfac
 
   return ordered;
 };
+
+type VisibleRailSurfacesOptions = {
+  railOrder: readonly string[];
+  planModeEnabled: boolean;
+  isVSCode: boolean;
+  screenWidth: number;
+  tabs: readonly { mode: ContextPanelMode }[];
+};
+
+/**
+ * The context panel rail's visible, user-ordered surfaces. Shared by the rail
+ * (for rendering and number badges) and the global surface-switch shortcut so
+ * both agree on which surface each digit maps to.
+ *
+ * Content-driven surfaces are hidden (not disabled) until content exists; an
+ * existing tab keeps them visible even if the content source went away.
+ */
+export const getVisibleContextRailSurfaces = (options: VisibleRailSurfacesOptions): ContextSurfaceDescriptor[] => {
+  return sortContextSurfaces(options.railOrder).filter((surface) => {
+    if (surface.id === 'plan' && !options.planModeEnabled) {
+      return false;
+    }
+    // The walkthrough needs room for a stop list beside real code, and its
+    // diffs come from OpenChamber's Git routes, which VS Code does not serve.
+    if (surface.id === 'walkthrough' && (options.isVSCode || options.screenWidth < WALKTHROUGH_MIN_WIDTH)) {
+      return false;
+    }
+    if (surface.availability === 'has-content') {
+      return options.tabs.some((tab) => tab.mode === surface.mode);
+    }
+    return true;
+  });
+};

From ce0e1cea275ad1e1991f71f47d466e6a42d8b85e Mon Sep 17 00:00:00 2001
From: Bohdan Triapitsyn <artmore@protonmail.com>
Date: Tue, 4 Aug 2026 22:41:09 +0300
Subject: [PATCH 14/57] fix(git): resolve the base branch from the repository
 instead of its name
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Follow-up to #2629, which stopped the walkthrough from comparing against a
branch that does not exist. The same guessing, and the same near-misses in how
the answer was applied, were left elsewhere:

- The default branch travelled as `rootBranchHint`, whose documented meaning is
  "the branch the project root worktree is on". It gets its own option, because
  a parameter that means two things is one the next caller gets wrong.
- A candidate equal to the branch being compared is skipped. In a plain checkout
  the root hint *is* the current branch, so it won every time and produced a
  comparison with itself; the repository default now wins there.
- The Changes and pull-request surfaces read the default branch too. A pull
  request opened against a branch that does not exist is a worse failure than a
  walkthrough that will not generate.
- `hasResolvableBaseBranch` matched `origin/feature/main` for a base of `main`,
  passing the check and then failing the comparison it exists to prevent.
- `getRangeDiff` promoted only `origin/<base>`. A base carried by any other
  remote stayed a bare name, which git resolves against refs/heads and nowhere
  else, so it failed exactly as before.
- `getBranches` dropped every branch of a remote that did not answer, turning
  "we could not ask" into "these branches are gone" — offline, that silently
  removed comparisons that work fine against local remote-tracking refs.
- A remote with no `remote/HEAD` is asked once with `ls-remote --symref` rather
  than falling back to the guess this data exists to replace.

The `defaultBranches` contract was documented under the status response; it
belongs to the branches response, which now has a section of its own.
---
 packages/ui/src/components/views/GitView.tsx  | 23 +++++-
 .../src/components/views/PullRequestView.tsx  | 24 +++++-
 .../components/views/git/baseBranch.test.ts   | 58 ++++++++++++++-
 .../ui/src/components/views/git/baseBranch.ts | 52 +++++++++++--
 .../views/walkthrough/WalkthroughView.tsx     |  9 ++-
 packages/web/server/lib/git/DOCUMENTATION.md  |  7 +-
 packages/web/server/lib/git/service.js        | 67 ++++++++++++++++-
 packages/web/server/lib/git/service.test.js   | 74 +++++++++++++++----
 .../server/lib/walkthrough/DOCUMENTATION.md   | 15 +++-
 9 files changed, 292 insertions(+), 37 deletions(-)

diff --git a/packages/ui/src/components/views/GitView.tsx b/packages/ui/src/components/views/GitView.tsx
index 06485c92..28fcf9f1 100644
--- a/packages/ui/src/components/views/GitView.tsx
+++ b/packages/ui/src/components/views/GitView.tsx
@@ -1417,12 +1417,32 @@ export const GitView: React.FC<GitViewProps> = ({ isActive }) => {
     }));
   }, [remotes, remoteBranches, remoteUrl, status?.tracking]);
 
+  const currentBranch = status?.current ?? null;
+
+  // The repository's own default branch, so a repo whose default is neither
+  // main, master nor develop stops being compared against a branch that does
+  // not exist.
+  const defaultBranch = React.useMemo(() => {
+    const trackingRemote = status?.tracking?.trim().split('/')[0];
+    return (trackingRemote && branches?.defaultBranches?.[trackingRemote])
+      ?? branches?.defaultBranches?.origin;
+  }, [branches, status?.tracking]);
+
   const baseBranch = React.useMemo(() => deriveBaseBranch({
     remoteNames: new Set(effectiveRemotes.map((remote) => remote.name)),
     localBranches,
     worktreeCreatedFromBranch: worktreeMetadata?.createdFromBranch,
     rootBranchHint,
-  }), [effectiveRemotes, localBranches, rootBranchHint, worktreeMetadata?.createdFromBranch]);
+    defaultBranch,
+    headBranch: currentBranch,
+  }), [
+    currentBranch,
+    defaultBranch,
+    effectiveRemotes,
+    localBranches,
+    rootBranchHint,
+    worktreeMetadata?.createdFromBranch,
+  ]);
 
   const updateTargetBranch = React.useMemo(() => {
     const remoteNames = effectiveRemotes.map((remote) => remote.name);
@@ -1511,7 +1531,6 @@ export const GitView: React.FC<GitViewProps> = ({ isActive }) => {
 
   const stagedCount = stagedChangeEntries.length;
   const isBusy = isLoading || syncAction !== null || commitAction !== null;
-  const currentBranch = status?.current ?? null;
   const canShowIntegrateCommitsSection = Boolean(
     worktreeMetadata && repoRootForIntegrate && sourceBranchForIntegrate && shouldShowIntegrateCommits
   );
diff --git a/packages/ui/src/components/views/PullRequestView.tsx b/packages/ui/src/components/views/PullRequestView.tsx
index 9f8bec34..baade489 100644
--- a/packages/ui/src/components/views/PullRequestView.tsx
+++ b/packages/ui/src/components/views/PullRequestView.tsx
@@ -213,14 +213,32 @@ export const PullRequestView: React.FC = () => {
     }));
   }, [remotes, remoteBranches, remoteUrl, status?.tracking]);
 
+  const currentBranch = status?.current ?? null;
+
+  // A pull request opened against a branch that does not exist is worse than a
+  // broken walkthrough, so this surface reads the repository's default branch
+  // too rather than guessing at main/master/develop.
+  const defaultBranch = React.useMemo(() => {
+    const trackingRemote = status?.tracking?.trim().split('/')[0];
+    return (trackingRemote && branches?.defaultBranches?.[trackingRemote])
+      ?? branches?.defaultBranches?.origin;
+  }, [branches, status?.tracking]);
+
   const baseBranch = React.useMemo(() => deriveBaseBranch({
     remoteNames: new Set(effectiveRemotes.map((remote) => remote.name)),
     localBranches,
     worktreeCreatedFromBranch: worktreeMetadata?.createdFromBranch,
     rootBranchHint,
-  }), [effectiveRemotes, localBranches, rootBranchHint, worktreeMetadata?.createdFromBranch]);
-
-  const currentBranch = status?.current ?? null;
+    defaultBranch,
+    headBranch: currentBranch,
+  }), [
+    currentBranch,
+    defaultBranch,
+    effectiveRemotes,
+    localBranches,
+    rootBranchHint,
+    worktreeMetadata?.createdFromBranch,
+  ]);
 
   if (!currentDirectory || !currentBranch) {
     return (
diff --git a/packages/ui/src/components/views/git/baseBranch.test.ts b/packages/ui/src/components/views/git/baseBranch.test.ts
index 18aaffb8..97a1fdee 100644
--- a/packages/ui/src/components/views/git/baseBranch.test.ts
+++ b/packages/ui/src/components/views/git/baseBranch.test.ts
@@ -2,13 +2,49 @@ import { describe, expect, test } from 'bun:test';
 import { deriveBaseBranch, hasResolvableBaseBranch } from './baseBranch';
 
 describe('deriveBaseBranch', () => {
-  test('prefers the remote default branch hint over conventional fallbacks', () => {
+  test('prefers the repository default branch over conventional fallbacks', () => {
     expect(deriveBaseBranch({
       remoteNames: new Set(['origin']),
       localBranches: ['next'],
-      rootBranchHint: 'origin/react',
+      defaultBranch: 'react',
     })).toBe('react');
   });
+
+  test('accepts a remote-qualified default branch', () => {
+    expect(deriveBaseBranch({
+      remoteNames: new Set(['origin']),
+      localBranches: ['next'],
+      defaultBranch: 'origin/react',
+    })).toBe('react');
+  });
+
+  test('keeps the more specific worktree origin ahead of the default branch', () => {
+    expect(deriveBaseBranch({
+      remoteNames: new Set(['origin']),
+      localBranches: ['next', 'react', 'feature'],
+      worktreeCreatedFromBranch: 'feature',
+      defaultBranch: 'react',
+    })).toBe('feature');
+  });
+
+  test('skips a hint that is the branch being compared', () => {
+    // In a plain checkout the project root is the current worktree, so the root
+    // branch hint is the current branch — a branch is never its own base.
+    expect(deriveBaseBranch({
+      remoteNames: new Set(['origin']),
+      localBranches: ['next', 'react'],
+      rootBranchHint: 'next',
+      defaultBranch: 'react',
+      headBranch: 'next',
+    })).toBe('react');
+  });
+
+  test('falls back to conventional names when nothing is known', () => {
+    expect(deriveBaseBranch({
+      remoteNames: new Set(['origin']),
+      localBranches: ['master', 'next'],
+    })).toBe('master');
+  });
 });
 
 describe('hasResolvableBaseBranch', () => {
@@ -21,10 +57,28 @@ describe('hasResolvableBaseBranch', () => {
   });
 
   test('accepts a base branch available through a remote-tracking ref', () => {
+    // Safe because getRangeDiff resolves a base that exists only on a remote
+    // through that remote rather than passing the bare name to git.
     expect(hasResolvableBaseBranch({
       baseBranch: 'main',
       localBranches: ['next'],
       remoteBranches: ['origin/main', 'origin/next'],
     })).toBe(true);
   });
+
+  test('does not accept a differently-scoped branch that merely ends the same way', () => {
+    expect(hasResolvableBaseBranch({
+      baseBranch: 'main',
+      localBranches: ['next'],
+      remoteBranches: ['origin/feature/main'],
+    })).toBe(false);
+  });
+
+  test('matches a base branch whose own name contains a slash', () => {
+    expect(hasResolvableBaseBranch({
+      baseBranch: 'release/2.0',
+      localBranches: ['next'],
+      remoteBranches: ['origin/release/2.0'],
+    })).toBe(true);
+  });
 });
diff --git a/packages/ui/src/components/views/git/baseBranch.ts b/packages/ui/src/components/views/git/baseBranch.ts
index 6409597b..c9937ca2 100644
--- a/packages/ui/src/components/views/git/baseBranch.ts
+++ b/packages/ui/src/components/views/git/baseBranch.ts
@@ -8,8 +8,30 @@ export const deriveBaseBranch = (options: {
   localBranches: readonly string[];
   worktreeCreatedFromBranch?: string | null;
   rootBranchHint?: string | null;
+  /**
+   * The repository's own default branch, read from a `remote/HEAD` symbolic
+   * ref. Its own option rather than another hint: `rootBranchHint` means "the
+   * branch the project root worktree is on", and a parameter that means two
+   * things is one the next caller gets wrong.
+   */
+  defaultBranch?: string | null;
+  /**
+   * The branch being compared. A branch is never its own base, so a candidate
+   * equal to it is skipped — in a plain checkout `rootBranchHint` *is* the
+   * current branch, and taking it produced a comparison with itself.
+   */
+  headBranch?: string | null;
 }): string => {
-  const { remoteNames, localBranches, worktreeCreatedFromBranch, rootBranchHint } = options;
+  const {
+    remoteNames,
+    localBranches,
+    worktreeCreatedFromBranch,
+    rootBranchHint,
+    defaultBranch,
+    headBranch,
+  } = options;
+
+  const head = typeof headBranch === 'string' ? headBranch.trim() : '';
 
   const normalizeBaseCandidate = (value: string): string => {
     if (!value) {
@@ -49,14 +71,22 @@ export const deriveBaseBranch = (options: {
     return normalized;
   };
 
-  const fromMeta = normalizeBaseCandidate(
-    typeof worktreeCreatedFromBranch === 'string' ? worktreeCreatedFromBranch : ''
-  );
+  const candidate = (value: unknown): string => {
+    const normalized = normalizeBaseCandidate(typeof value === 'string' ? value : '');
+    return normalized && normalized !== head ? normalized : '';
+  };
+
+  const fromMeta = candidate(worktreeCreatedFromBranch);
   if (fromMeta) return fromMeta;
 
-  const fromHint = normalizeBaseCandidate(typeof rootBranchHint === 'string' ? rootBranchHint : '');
+  const fromHint = candidate(rootBranchHint);
   if (fromHint) return fromHint;
 
+  // Authoritative where the hints are guesses: this is what the repository says
+  // its default branch is, so it outranks the conventional names below.
+  const fromDefault = candidate(defaultBranch);
+  if (fromDefault) return fromDefault;
+
   if (localBranches.includes('main')) return 'main';
   if (localBranches.includes('master')) return 'master';
   if (localBranches.includes('develop')) return 'develop';
@@ -67,6 +97,11 @@ export const deriveBaseBranch = (options: {
  * Whether a base branch can be resolved locally or through one of the active
  * remote-tracking refs. Callers must not offer comparisons against the `main`
  * fallback when that ref does not actually exist in the repository.
+ *
+ * `remoteBranches` are remote-relative (`origin/main`, `origin/feature/x`), so
+ * the remote name is dropped and the rest compared whole. A suffix test matched
+ * `origin/feature/main` for a base of `main`, which passes the check and then
+ * fails the comparison it was meant to prevent.
  */
 export const hasResolvableBaseBranch = (options: {
   baseBranch: string;
@@ -74,6 +109,9 @@ export const hasResolvableBaseBranch = (options: {
   remoteBranches: readonly string[];
 }): boolean => {
   const { baseBranch, localBranches, remoteBranches } = options;
-  return localBranches.includes(baseBranch)
-    || remoteBranches.some((branch) => branch.endsWith(`/${baseBranch}`));
+  if (localBranches.includes(baseBranch)) return true;
+  return remoteBranches.some((branch) => {
+    const slashIndex = branch.indexOf('/');
+    return slashIndex > 0 && branch.slice(slashIndex + 1) === baseBranch;
+  });
 };
diff --git a/packages/ui/src/components/views/walkthrough/WalkthroughView.tsx b/packages/ui/src/components/views/walkthrough/WalkthroughView.tsx
index fcca3dab..51b20387 100644
--- a/packages/ui/src/components/views/walkthrough/WalkthroughView.tsx
+++ b/packages/ui/src/components/views/walkthrough/WalkthroughView.tsx
@@ -185,9 +185,14 @@ export const WalkthroughView = ({ directory }: WalkthroughViewProps) => {
         .filter(Boolean)
     );
     const trackingRemote = status?.tracking?.split('/')[0];
-    const rootBranchHint = (trackingRemote && branches?.defaultBranches?.[trackingRemote])
+    const defaultBranch = (trackingRemote && branches?.defaultBranches?.[trackingRemote])
       ?? branches?.defaultBranches?.origin;
-    const baseRef = deriveBaseBranch({ remoteNames, localBranches, rootBranchHint });
+    const baseRef = deriveBaseBranch({
+      remoteNames,
+      localBranches,
+      defaultBranch,
+      headBranch: headRef,
+    });
     if (!baseRef || baseRef === headRef || !hasResolvableBaseBranch({ baseBranch: baseRef, localBranches, remoteBranches })) {
       return null;
     }
diff --git a/packages/web/server/lib/git/DOCUMENTATION.md b/packages/web/server/lib/git/DOCUMENTATION.md
index 8bcbb964..98368370 100644
--- a/packages/web/server/lib/git/DOCUMENTATION.md
+++ b/packages/web/server/lib/git/DOCUMENTATION.md
@@ -105,13 +105,18 @@ The following functions are internal helpers used by exported functions:
 - `ahead`: Number of commits ahead of upstream.
 - `behind`: Number of commits behind upstream.
 - `upstreamComparison`: Optional comparison against `upstream/<current-branch>`, with `{ remote, branch, ahead, behind }`.
-- `defaultBranches`: Remote default branches derived from local symbolic refs such as `remotes/origin/HEAD -> origin/main`, keyed by remote name. Omitted by runtimes that do not provide this Git metadata.
 - `files`: Array of file objects with `path`, `index`, `working_dir` status codes.
 - `isClean`: Boolean indicating if working tree is clean.
 - `diffStats`: Object mapping file paths to `{ insertions, deletions }`.
 - `mergeInProgress`: Object with `{ head, message }` if merge in progress.
 - `rebaseInProgress`: Object with `{ headName, onto }` if rebase in progress.
 
+### Branches Response
+- `all`: Local branches plus remote-tracking branches that still exist on their remote. A remote that fails to answer keeps its branches in the list: "we could not ask" must not be reported as "these branches are gone", because callers use this list to decide whether a base branch exists at all.
+- `current`: Current branch name.
+- `branches`: Per-branch detail keyed by branch name, as reported by `git branch`.
+- `defaultBranches`: Each remote's default branch, keyed by remote name. Read from the local `remotes/<name>/HEAD` symbolic ref; for a remote that has none — clone writes it, a hand-added remote may not — the remote itself is asked once with `ls-remote --symref`. A remote that answers neither is absent rather than guessed, and consumers fall back to conventional branch names. Omitted entirely by runtimes that do not provide this Git metadata.
+
 ### Runtime availability of range diffs
 - `GET /api/git/range-diff` is served by the OpenChamber web server, so it is available to web, desktop, and mobile clients. The shared `GitAPI.getGitRangeDiff` is therefore optional: web supplies the HTTP implementation, and VS Code does not implement it because the extension host serves Git through its own bridge rather than these routes. Features built on range diffs (currently the AI diff walkthrough) are not offered in VS Code.
 
diff --git a/packages/web/server/lib/git/service.js b/packages/web/server/lib/git/service.js
index ed64b7c5..d058dd91 100644
--- a/packages/web/server/lib/git/service.js
+++ b/packages/web/server/lib/git/service.js
@@ -2446,6 +2446,27 @@ export async function getRangeDiff(directory, { base, head, path: filePath, cont
     // ignore
   }
 
+  // Not every repository has an `origin`. When the base names a branch that
+  // exists only on another remote, a bare name does not resolve — git looks in
+  // refs/heads, not across remotes — and the diff fails with "ambiguous
+  // argument". Fall back to whichever remote actually carries it.
+  if (resolvedBase === baseRef && !/[*?[\]^~:\\]/.test(baseRef)) {
+    const resolvesLocally = await git
+      .raw(['rev-parse', '--verify', `refs/heads/${baseRef}`])
+      .then((value) => Boolean(String(value || '').trim()))
+      .catch(() => false);
+
+    if (!resolvesLocally) {
+      const remoteMatch = await git
+        .raw(['for-each-ref', '--count=1', '--format=%(refname:short)', `refs/remotes/*/${baseRef}`])
+        .then((value) => String(value || '').trim())
+        .catch(() => '');
+      if (remoteMatch) {
+        resolvedBase = remoteMatch;
+      }
+    }
+  }
+
   const args = ['diff', '--no-color'];
   if (typeof contextLines === 'number' && !Number.isNaN(contextLines)) {
     args.push(`-U${Math.max(0, contextLines)}`);
@@ -3387,13 +3408,15 @@ export async function getBranches(directory) {
 }
 
 async function getRemoteDefaultBranches(git) {
+  let defaults = {};
+
   try {
     const refs = await git.raw([
       'for-each-ref',
       '--format=%(refname) %(symref)',
       'refs/remotes',
     ]);
-    return Object.fromEntries(
+    defaults = Object.fromEntries(
       refs.trim().split('\n').flatMap((line) => {
         const [ref, symbolicRef] = line.split(' ');
         const match = ref.match(/^refs\/remotes\/([^/]+)\/HEAD$/);
@@ -3404,8 +3427,38 @@ async function getRemoteDefaultBranches(git) {
       })
     );
   } catch {
-    return {};
+    defaults = {};
   }
+
+  // `remote/HEAD` is written by clone and by `git remote set-head`; a remote
+  // added by hand may never have one. Without this the caller falls back to
+  // guessing main/master/develop, which is exactly the guess this data exists
+  // to replace — so ask the remote itself, but only for the remotes that are
+  // actually missing an answer.
+  try {
+    const remotes = await git.getRemotes();
+    const missing = remotes.filter((remote) => remote?.name && !defaults[remote.name]);
+    if (missing.length === 0) return defaults;
+
+    const resolved = await Promise.all(missing.map(async (remote) => {
+      try {
+        const output = await git.raw(['ls-remote', '--symref', remote.name, 'HEAD']);
+        const match = String(output || '').match(/^ref:\s+refs\/heads\/(.+?)\s+HEAD$/m);
+        return match ? [remote.name, match[1]] : null;
+      } catch {
+        // Unreachable or refusing: no answer is better than a guessed one.
+        return null;
+      }
+    }));
+
+    for (const entry of resolved) {
+      if (entry) defaults[entry[0]] = entry[1];
+    }
+  } catch {
+    // Remote list unavailable; the local symrefs are still valid.
+  }
+
+  return defaults;
 }
 
 async function filterActiveRemoteBranches(git, remoteBranches) {
@@ -3413,6 +3466,13 @@ async function filterActiveRemoteBranches(git, remoteBranches) {
     const remotes = await git.getRemotes();
     const branchesByRemote = new Map();
 
+    // A remote that did not answer says nothing about its branches. Dropping
+    // them would turn "we could not ask" into "these branches are gone", and
+    // callers use this list to decide whether a base branch exists at all — so
+    // offline would silently remove comparisons that work perfectly well
+    // against the local remote-tracking refs.
+    const unreachableRemotes = new Set();
+
     await Promise.all(remotes.map(async (remote) => {
       try {
         const lsRemoteResult = await git.raw(['ls-remote', '--heads', remote.name]);
@@ -3426,7 +3486,7 @@ async function filterActiveRemoteBranches(git, remoteBranches) {
         }
         branchesByRemote.set(remote.name, actualRemoteBranches);
       } catch {
-        // Skip remotes that fail (e.g., unreachable)
+        unreachableRemotes.add(remote.name);
       }
     }));
 
@@ -3435,6 +3495,7 @@ async function filterActiveRemoteBranches(git, remoteBranches) {
       if (!match) return false;
       const remoteName = remoteBranch.split('/')[1];
       const branchName = match[1];
+      if (unreachableRemotes.has(remoteName)) return true;
       return branchesByRemote.get(remoteName)?.has(branchName) ?? false;
     });
   } catch (error) {
diff --git a/packages/web/server/lib/git/service.test.js b/packages/web/server/lib/git/service.test.js
index 40f0c054..7b06d022 100644
--- a/packages/web/server/lib/git/service.test.js
+++ b/packages/web/server/lib/git/service.test.js
@@ -11,6 +11,7 @@ import {
   createWorktree,
   getWorktreeBootstrapStatus,
   getBranches,
+  getRangeDiff,
   getStatus,
   isGitRepository,
   populateWorktreeWithLockRecovery,
@@ -48,6 +49,28 @@ const runGit = (cwd, args) =>
     stdio: ['ignore', 'pipe', 'pipe'],
   });
 
+/**
+ * A repository on `next` whose only remote publishes `defaultBranch` and has it
+ * recorded as that remote's HEAD — the shape of every repository whose default
+ * branch is not one of the conventional names.
+ */
+const createRepositoryWithRemote = ({ remoteName = 'origin', defaultBranch = 'react' } = {}) => {
+  const remote = createTempDir();
+  const repository = createTempDir();
+  runGit(remote, ['init', '--bare', `--initial-branch=${defaultBranch}`]);
+  runGit(repository, ['init', '-b', 'next']);
+  runGit(repository, ['config', 'user.email', 'test@example.com']);
+  runGit(repository, ['config', 'user.name', 'Test']);
+  fs.writeFileSync(path.join(repository, 'README.md'), '# Test\n');
+  runGit(repository, ['add', 'README.md']);
+  runGit(repository, ['commit', '-m', 'init']);
+  runGit(repository, ['remote', 'add', remoteName, remote]);
+  runGit(repository, ['push', remoteName, `HEAD:${defaultBranch}`]);
+  runGit(repository, ['fetch', remoteName]);
+  runGit(repository, ['remote', 'set-head', remoteName, '--auto']);
+  return { remote, repository };
+};
+
 const canRunGit = () => {
   try {
     execFileSync('git', ['--version'], { stdio: 'ignore' });
@@ -992,22 +1015,47 @@ describe('hash validation', () => {
 
 describe.runIf(canRunGit())('getBranches', () => {
   it('returns a remote default branch whose name is not a conventional fallback', async () => {
-    const remote = createTempDir();
-    const repository = createTempDir();
-    runGit(remote, ['init', '--bare', '--initial-branch=react']);
-    runGit(repository, ['init', '-b', 'next']);
-    runGit(repository, ['config', 'user.email', 'test@example.com']);
-    runGit(repository, ['config', 'user.name', 'Test']);
-    fs.writeFileSync(path.join(repository, 'README.md'), '# Test\n');
-    runGit(repository, ['add', 'README.md']);
-    runGit(repository, ['commit', '-m', 'init']);
-    runGit(repository, ['remote', 'add', 'origin', remote]);
-    runGit(repository, ['push', 'origin', 'HEAD:react']);
-    runGit(repository, ['fetch', 'origin']);
-    runGit(repository, ['remote', 'set-head', 'origin', '--auto']);
+    const { repository } = createRepositoryWithRemote({ remoteName: 'origin', defaultBranch: 'react' });
 
     await expect(getBranches(repository)).resolves.toMatchObject({
       defaultBranches: { origin: 'react' },
     });
   });
+
+  it('asks the remote when no local remote/HEAD exists', async () => {
+    const { repository } = createRepositoryWithRemote({ remoteName: 'origin', defaultBranch: 'react' });
+    // A hand-added remote can end up without this ref; the branch it points at
+    // is still knowable, and guessing instead is the bug this data replaces.
+    runGit(repository, ['remote', 'set-head', 'origin', '--delete']);
+
+    await expect(getBranches(repository)).resolves.toMatchObject({
+      defaultBranches: { origin: 'react' },
+    });
+  });
+
+  it('keeps the branches of a remote that cannot be reached', async () => {
+    const { repository, remote } = createRepositoryWithRemote({ remoteName: 'origin', defaultBranch: 'react' });
+    fs.rmSync(remote, { recursive: true, force: true });
+
+    const branches = await getBranches(repository);
+
+    // "We could not ask" is not "the branch is gone": callers read this list to
+    // decide whether a base branch exists at all.
+    expect(branches.all).toContain('remotes/origin/react');
+  });
+});
+
+describe.runIf(canRunGit())('getRangeDiff', () => {
+  it('resolves a base that exists only on a remote other than origin', async () => {
+    const { repository } = createRepositoryWithRemote({ remoteName: 'upstream', defaultBranch: 'react' });
+    // Only refs/remotes/upstream/react carries the base — git cannot resolve the
+    // bare name, so an unqualified `react...next` fails with "ambiguous argument".
+    fs.writeFileSync(path.join(repository, 'feature.txt'), 'work\n');
+    runGit(repository, ['add', 'feature.txt']);
+    runGit(repository, ['commit', '-m', 'feature']);
+
+    const diff = await getRangeDiff(repository, { base: 'react', head: 'next' });
+
+    expect(diff).toContain('feature.txt');
+  });
 });
diff --git a/packages/web/server/lib/walkthrough/DOCUMENTATION.md b/packages/web/server/lib/walkthrough/DOCUMENTATION.md
index 61821f89..1d0cc404 100644
--- a/packages/web/server/lib/walkthrough/DOCUMENTATION.md
+++ b/packages/web/server/lib/walkthrough/DOCUMENTATION.md
@@ -55,10 +55,17 @@ written against staged code never silently re-anchors onto an unstaged edit.
 | `branch` | `branch` | `getRangeDiff` uses three-dot `base...head`, so work merged in from the base branch is excluded |
 | `pr` | `pr:<number>` | GitHub returns the merge-base diff, matching the branch semantics |
 
-For the current-branch source, the UI prefers the default branch of the current
-branch's tracking remote (from its local `remote/HEAD` symbolic ref), then uses
-the existing conventional-branch fallback. It does not offer the source when the
-chosen base cannot be resolved locally or through a remote-tracking ref.
+For the current-branch source, the UI takes the base from the default branch of
+the current branch's tracking remote (`defaultBranches` in the branches
+response), and only then falls back to the conventional names. It does not offer
+the source at all when the chosen base exists neither locally nor on a remote —
+a repository whose default is neither `main`, `master` nor `develop` used to be
+handed `main...<head>`, which git rejects outright.
+
+A base that exists only on a remote still works: `getRangeDiff` prefers
+`origin/<base>` when it exists, and otherwise resolves the base through whichever
+remote carries it, because a bare branch name git cannot find in `refs/heads`
+fails the same way.
 
 The panel offers the current branch's pull request on its own: it registers with
 the shared GitHub PR status store (`useGitHubPrStatusStore`) rather than waiting

From 094f728777b792cd51ade6c2b86ca3dac2858440 Mon Sep 17 00:00:00 2001
From: Bohdan Triapitsyn <artmore@protonmail.com>
Date: Wed, 5 Aug 2026 03:06:35 +0300
Subject: [PATCH 15/57] perf(ui): swap the session activity spinner for a dot
 and a turn timer
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The spinner ran a CSS animation on every active row for the whole turn,
repainting a composited layer at frame rate. Rows now carry a static dot —
primary while running, info while unread — and the metadata slot on the right
shows how long the turn has been going, updating once per second in the dot's
colour. The counter is the motion the spinner used to provide, at 1 fps.
Collapsed groups, folders and projects take the dot only, since one counter
cannot speak for several running turns.

Elapsed time is measured client-side because SessionStatus carries no
timestamps, and starts are persisted so a reload resumes the same count. Two
rules keep that honest. Only a liveness stamp — refreshed while a session is
observed active, stamped as the page hides, and compared against the page's
navigation start so a slow bootstrap is not charged to the absence — and a 90s
adoption window may expire a record; a snapshot that cannot yet see a session
is not evidence its turn ended. And a busy event is never read as a turn
boundary, because OpenCode republishes busy at every step of the agent loop, so
after a reload one of those repeats normally beats the first status snapshot.
Idle and error events do end a turn, and retire the record with it.

Snapshot reconciliation walks the running turns and asks whether the snapshot
covers each one, rather than being handed everything it covers: only a live
start can settle, so the pass scales with timing work instead of with the
directory's session list, and allocates nothing per poll.

Also applied to the mobile sessions sheet and session switcher. The shared
duration ticker moves to hooks/ now that it has a second consumer.
---
 .../ui/src/apps/MobileSessionSwitcher.tsx     |  27 +-
 packages/ui/src/apps/MobileSessionsSheet.tsx  |  26 +-
 packages/ui/src/apps/runtimeEndpointReset.ts  |   4 +
 .../chat/message/parts/ToolPart.tsx           |   2 +-
 .../session/SessionActivityDuration.tsx       |  58 +++
 .../src/components/session/SessionSidebar.tsx |   9 +-
 .../sessionActivityDurationFormat.test.ts     |  34 ++
 .../session/sessionActivityDurationFormat.ts  |  32 ++
 .../session/sidebar/DOCUMENTATION.md          |   2 +
 .../session/sidebar/SessionNodeItem.tsx       |  97 ++--
 .../sidebar/collapsedActivityIndicator.tsx    |  15 +-
 .../parts => hooks}/useDurationTicker.ts      |   4 +
 packages/ui/src/lib/i18n/messages/de.ts       |   5 +
 packages/ui/src/lib/i18n/messages/en.ts       |   5 +
 packages/ui/src/lib/i18n/messages/es.ts       |   5 +
 packages/ui/src/lib/i18n/messages/fr.ts       |   5 +
 packages/ui/src/lib/i18n/messages/ja.ts       |   5 +
 packages/ui/src/lib/i18n/messages/ko.ts       |   5 +
 packages/ui/src/lib/i18n/messages/pl.ts       |   5 +
 packages/ui/src/lib/i18n/messages/pt-BR.ts    |   5 +
 packages/ui/src/lib/i18n/messages/uk.ts       |   5 +
 packages/ui/src/lib/i18n/messages/zh-CN.ts    |   5 +
 packages/ui/src/lib/i18n/messages/zh-TW.ts    |   5 +
 packages/ui/src/sync/DOCUMENTATION.md         |  11 +
 packages/ui/src/sync/global-session-status.ts |  30 +-
 .../src/sync/session-activity-timing.test.ts  | 310 ++++++++++++
 .../ui/src/sync/session-activity-timing.ts    | 444 ++++++++++++++++++
 27 files changed, 1094 insertions(+), 66 deletions(-)
 create mode 100644 packages/ui/src/components/session/SessionActivityDuration.tsx
 create mode 100644 packages/ui/src/components/session/sessionActivityDurationFormat.test.ts
 create mode 100644 packages/ui/src/components/session/sessionActivityDurationFormat.ts
 rename packages/ui/src/{components/chat/message/parts => hooks}/useDurationTicker.ts (89%)
 create mode 100644 packages/ui/src/sync/session-activity-timing.test.ts
 create mode 100644 packages/ui/src/sync/session-activity-timing.ts

diff --git a/packages/ui/src/apps/MobileSessionSwitcher.tsx b/packages/ui/src/apps/MobileSessionSwitcher.tsx
index 4e2a44a8..c05b9ecf 100644
--- a/packages/ui/src/apps/MobileSessionSwitcher.tsx
+++ b/packages/ui/src/apps/MobileSessionSwitcher.tsx
@@ -1,7 +1,7 @@
 import React from 'react';
 import type { Session } from '@opencode-ai/sdk/v2';
 
-import { Icon } from '@/components/icon/Icon';
+import { SessionActivityDuration } from '@/components/session/SessionActivityDuration';
 import { formatSessionCompactDateLabel } from '@/components/session/sidebar/utils';
 import { useSwitcherItems } from '@/components/session/sidebar/hooks/useSwitcherItems';
 import { useTabletLayout } from '@/lib/device';
@@ -10,6 +10,7 @@ import { cn } from '@/lib/utils';
 import { refreshGlobalSessions, resolveGlobalSessionDirectory } from '@/stores/useGlobalSessionsStore';
 import { useProjectsStore } from '@/stores/useProjectsStore';
 import { useSessionUnseenCount } from '@/sync/notification-store';
+import { useHasSessionActivityDuration } from '@/sync/session-activity-timing';
 import { useSessionUIStore } from '@/sync/session-ui-store';
 import { useGlobalSessionStatus } from '@/sync/sync-context';
 
@@ -35,6 +36,8 @@ const SwitcherRow: React.FC<{
   const statusType = status?.type ?? 'idle';
   const isStreaming = statusType === 'busy' || statusType === 'retry';
   const showUnreadDot = !isStreaming && unseenCount > 0 && !active;
+  const hasActivityDuration = useHasSessionActivityDuration(session.id, isStreaming);
+  const showActivityDuration = (isStreaming || showUnreadDot) && hasActivityDuration;
   const timeLabel = formatSessionCompactDateLabel(session.time?.updated ?? session.time?.created ?? 0);
 
   return (
@@ -56,12 +59,24 @@ const SwitcherRow: React.FC<{
         ) : null}
       </span>
       {/* Activity sits on the right, before the time — no reserved left gutter. */}
-      {isStreaming ? (
-        <Icon name="loader-4" className="size-3.5 shrink-0 animate-spin text-primary" aria-hidden />
-      ) : showUnreadDot ? (
-        <span className="size-1.5 shrink-0 rounded-full bg-[var(--status-info)]" aria-hidden />
+      {isStreaming || showUnreadDot ? (
+        <span
+          className={cn(
+            'size-1.5 shrink-0 rounded-full',
+            isStreaming ? 'bg-primary' : 'bg-[var(--status-info)]',
+          )}
+          aria-hidden
+        />
       ) : null}
-      {timeLabel ? (
+      {/* The elapsed turn takes the time slot while it matters, then hands it
+          back to the relative timestamp. */}
+      {showActivityDuration ? (
+        <SessionActivityDuration
+          sessionId={session.id}
+          running={isStreaming}
+          className="typography-micro"
+        />
+      ) : timeLabel ? (
         <span className="shrink-0 typography-micro text-muted-foreground tabular-nums">{timeLabel}</span>
       ) : null}
     </button>
diff --git a/packages/ui/src/apps/MobileSessionsSheet.tsx b/packages/ui/src/apps/MobileSessionsSheet.tsx
index 5f93651b..43a28f32 100644
--- a/packages/ui/src/apps/MobileSessionsSheet.tsx
+++ b/packages/ui/src/apps/MobileSessionsSheet.tsx
@@ -64,6 +64,8 @@ import {
 import { useSessionUIStore } from '@/sync/session-ui-store';
 import { useAllLiveSessions, useGlobalSessionStatus } from '@/sync/sync-context';
 import { useSessionUnseenCount } from '@/sync/notification-store';
+import { useHasSessionActivityDuration } from '@/sync/session-activity-timing';
+import { SessionActivityDuration } from '@/components/session/SessionActivityDuration';
 import type { WorktreeMetadata } from '@/types/worktree';
 
 import { MobileDeleteWorktreeDialog } from './MobileDeleteWorktreeDialog';
@@ -476,6 +478,8 @@ const SessionRow: React.FC<{
   const statusType = liveStatus?.type ?? 'idle';
   const isStreaming = statusType === 'busy' || statusType === 'retry';
   const showUnreadDot = !isStreaming && unseenCount > 0 && !active;
+  const hasActivityDuration = useHasSessionActivityDuration(session.id, isStreaming);
+  const showActivityDuration = (isStreaming || showUnreadDot) && hasActivityDuration;
 
   const contentRef = React.useRef<HTMLDivElement>(null);
   const startRef = React.useRef<{ x: number; y: number } | null>(null);
@@ -616,10 +620,14 @@ const SessionRow: React.FC<{
               onToggleChildren?.();
             }}
           >
-            {isStreaming ? (
-              <Icon name="loader-4" className="size-3.5 animate-spin text-primary" />
-            ) : showUnreadDot ? (
-              <span className="size-1.5 rounded-full bg-[var(--status-info)]" aria-hidden />
+            {isStreaming || showUnreadDot ? (
+              <span
+                className={cn(
+                  'size-1.5 rounded-full',
+                  isStreaming ? 'bg-primary' : 'bg-[var(--status-info)]',
+                )}
+                aria-hidden
+              />
             ) : (
               <RiArrowDownSLine className={cn('size-[18px] transition-transform duration-150', expanded ? 'rotate-0' : '-rotate-90')} />
             )}
@@ -664,7 +672,15 @@ const SessionRow: React.FC<{
               >
                 {title}
               </span>
-              {time ? (
+              {/* The elapsed turn takes the time slot while it matters, then
+                  hands it back to the relative timestamp. */}
+              {showActivityDuration ? (
+                <SessionActivityDuration
+                  sessionId={session.id}
+                  running={isStreaming}
+                  className="typography-micro"
+                />
+              ) : time ? (
                 <span className="shrink-0 typography-micro text-muted-foreground tabular-nums">{time}</span>
               ) : null}
             </span>
diff --git a/packages/ui/src/apps/runtimeEndpointReset.ts b/packages/ui/src/apps/runtimeEndpointReset.ts
index e92a4063..b430cfc9 100644
--- a/packages/ui/src/apps/runtimeEndpointReset.ts
+++ b/packages/ui/src/apps/runtimeEndpointReset.ts
@@ -17,6 +17,7 @@ import { useSessionUIStore } from '@/sync/session-ui-store';
 import { resetStreamingState } from '@/sync/streaming';
 import { useGlobalSessionStatusStore } from '@/sync/global-session-status';
 import { resetSessionOrdering } from '@/sync/session-ordering';
+import { resetSessionActivityTiming } from '@/sync/session-activity-timing';
 import { syncDesktopSettings } from '@/lib/persistence';
 
 // Same-device transport switch (LAN⇄relay for one paired device): rebind the SDK
@@ -56,6 +57,9 @@ export const resetAppForRuntimeEndpointChange = (detail: RuntimeEndpointChangedD
   useGlobalSessionsStore.getState().resetForRuntimeSwitch();
   useGlobalSessionStatusStore.setState({ statusById: new Map() });
   resetSessionOrdering();
+  // Turn timings belong to the previous instance's sessions, and the reset also
+  // restarts the resume window so the switch is treated as a fresh load.
+  resetSessionActivityTiming();
   usePermissionStore.getState().reset();
   useFileSearchStore.getState().resetForRuntimeSwitch();
   useGitStore.getState().resetForRuntimeSwitch(detail.runtimeKey);
diff --git a/packages/ui/src/components/chat/message/parts/ToolPart.tsx b/packages/ui/src/components/chat/message/parts/ToolPart.tsx
index ee4983de..2969dd85 100644
--- a/packages/ui/src/components/chat/message/parts/ToolPart.tsx
+++ b/packages/ui/src/components/chat/message/parts/ToolPart.tsx
@@ -42,7 +42,7 @@ import { DiffViewToggle, type DiffViewMode } from '../DiffViewToggle';
 import { MinDurationShineText } from './MinDurationShineText';
 import { ToolRevealOnMount } from './ToolRevealOnMount';
 import { getToolIcon } from './toolPresentation';
-import { useDurationTickerNow } from './useDurationTicker';
+import { useDurationTickerNow } from '@/hooks/useDurationTicker';
 import {
     buildTaskSummaryEntriesFromSession,
     normalizeTaskSummaryEntries,
diff --git a/packages/ui/src/components/session/SessionActivityDuration.tsx b/packages/ui/src/components/session/SessionActivityDuration.tsx
new file mode 100644
index 00000000..92499e2b
--- /dev/null
+++ b/packages/ui/src/components/session/SessionActivityDuration.tsx
@@ -0,0 +1,58 @@
+import React from 'react';
+import { cn } from '@/lib/utils';
+import { useI18n } from '@/lib/i18n';
+import { useDurationTickerNow } from '@/hooks/useDurationTicker';
+import {
+  useSessionActivityStartedAt,
+  useSessionSettledDurationMs,
+} from '@/sync/session-activity-timing';
+import { formatSessionActivityDuration } from './sessionActivityDurationFormat';
+
+/** One update per second: the readout is the animation, at 1 fps instead of 60. */
+const TICK_MS = 1000;
+
+/**
+ * Elapsed time of a session's current turn, or of the turn that just finished.
+ * Colored to match the row's status dot in each state, so the pair reads as one
+ * indicator rather than two.
+ *
+ * Deliberately a leaf. The tick re-renders this span alone rather than the
+ * session row around it, which is what makes a live counter cheaper than the
+ * spinner it replaced — that spinner repainted a composited layer per row every
+ * frame for as long as the session ran.
+ */
+export const SessionActivityDuration: React.FC<{
+  sessionId: string;
+  /** Turn still running (`busy` or `retry`); false renders the settled total. */
+  running: boolean;
+  className?: string;
+}> = ({ sessionId, running, className }) => {
+  const { t } = useI18n();
+  const startedAt = useSessionActivityStartedAt(sessionId);
+  const settledMs = useSessionSettledDurationMs(sessionId);
+  const now = useDurationTickerNow(running, TICK_MS);
+
+  const durationMs = running ? Math.max(0, now - (startedAt ?? now)) : settledMs;
+  if (durationMs === undefined) return null;
+
+  const label = formatSessionActivityDuration(durationMs, t);
+  const description = running
+    ? t('sessions.sidebar.session.status.activeFor', { duration: label })
+    : t('sessions.sidebar.session.status.lastTurnDuration', { duration: label });
+
+  return (
+    <span
+      className={cn(
+        'shrink-0 tabular-nums',
+        // The readout wears its dot's color, so the row reads as one signal:
+        // primary while the turn runs, info once it is waiting to be read.
+        running ? 'text-primary' : 'text-[var(--status-info)]',
+        className,
+      )}
+      aria-label={description}
+      title={description}
+    >
+      {label}
+    </span>
+  );
+};
diff --git a/packages/ui/src/components/session/SessionSidebar.tsx b/packages/ui/src/components/session/SessionSidebar.tsx
index acd52fad..f7ce5a3b 100644
--- a/packages/ui/src/components/session/SessionSidebar.tsx
+++ b/packages/ui/src/components/session/SessionSidebar.tsx
@@ -17,7 +17,6 @@ import { useUIStore } from '@/stores/useUIStore';
 import { getDeferredSafeStorage } from '@/stores/utils/safeStorage';
 import { useGitStore, useGitAllBranches, useGitRepoStatusMap } from '@/stores/useGitStore';
 import { isVSCodeRuntime } from '@/lib/desktop';
-import { Icon } from '@/components/icon/Icon';
 import { TooltipProvider } from '@/components/ui/tooltip';
 import { NewWorktreeDialog } from './NewWorktreeDialog';
 import { useSessionFoldersStore } from '@/stores/useSessionFoldersStore';
@@ -243,12 +242,14 @@ const ProjectAggregateStatusIndicator: React.FC<{ directories: Array<string | nu
     return false;
   }, [directorySet]));
 
+  // Aggregate header: dot only. A collapsed project can hold several running
+  // turns, so a single elapsed counter would have nothing to count.
   if (hasBusySession) {
     return (
-      <Icon
-        name="loader-4"
-        className="h-3 w-3 animate-spin text-primary"
+      <span
+        className="h-1.5 w-1.5 rounded-full bg-primary"
         aria-label={t('sessions.sidebar.session.status.active')}
+        title={t('sessions.sidebar.session.status.active')}
       />
     );
   }
diff --git a/packages/ui/src/components/session/sessionActivityDurationFormat.test.ts b/packages/ui/src/components/session/sessionActivityDurationFormat.test.ts
new file mode 100644
index 00000000..4ee81a5a
--- /dev/null
+++ b/packages/ui/src/components/session/sessionActivityDurationFormat.test.ts
@@ -0,0 +1,34 @@
+import { describe, expect, test } from 'bun:test';
+
+import { dict as enDict } from '@/lib/i18n/messages/en';
+import { formatMessage, type I18nKey, type I18nParams } from '@/lib/i18n';
+import { formatSessionActivityDuration } from './sessionActivityDurationFormat';
+
+const t = (key: I18nKey, params?: I18nParams): string => formatMessage(enDict, key, params);
+
+const format = (ms: number): string => formatSessionActivityDuration(ms, t);
+
+describe('formatSessionActivityDuration', () => {
+  test('renders seconds below a minute', () => {
+    expect(format(0)).toBe('0s');
+    expect(format(999)).toBe('0s');
+    expect(format(7_400)).toBe('7s');
+    expect(format(59_999)).toBe('59s');
+  });
+
+  test('renders minutes and seconds below an hour', () => {
+    expect(format(60_000)).toBe('1m 0s');
+    expect(format(83_000)).toBe('1m 23s');
+    expect(format(59 * 60_000 + 59_000)).toBe('59m 59s');
+  });
+
+  test('drops seconds past an hour so the label stays narrow', () => {
+    expect(format(3_600_000)).toBe('1h 0m');
+    expect(format(3_600_000 + 2 * 60_000 + 33_000)).toBe('1h 2m');
+    expect(format(25 * 3_600_000)).toBe('25h 0m');
+  });
+
+  test('clamps a negative duration rather than rendering a negative count', () => {
+    expect(format(-5_000)).toBe('0s');
+  });
+});
diff --git a/packages/ui/src/components/session/sessionActivityDurationFormat.ts b/packages/ui/src/components/session/sessionActivityDurationFormat.ts
new file mode 100644
index 00000000..5f710609
--- /dev/null
+++ b/packages/ui/src/components/session/sessionActivityDurationFormat.ts
@@ -0,0 +1,32 @@
+import type { I18nKey, I18nParams } from '@/lib/i18n';
+
+type Translate = (key: I18nKey, params?: I18nParams) => string;
+
+const SECOND_MS = 1000;
+const MINUTE_MS = 60 * SECOND_MS;
+const HOUR_MS = 60 * MINUTE_MS;
+
+/**
+ * Compact turn duration for a session row: `7s`, `1m 23s`, `1h 2m`.
+ *
+ * Seconds are dropped past an hour so the label cannot outgrow the row's
+ * metadata slot, and the unit suffixes are translated rather than concatenated
+ * so locales that place or spell them differently stay correct.
+ */
+export const formatSessionActivityDuration = (durationMs: number, t: Translate): string => {
+  const total = Math.max(0, durationMs);
+
+  if (total < MINUTE_MS) {
+    return t('common.duration.secondsCompact', { seconds: Math.floor(total / SECOND_MS) });
+  }
+  if (total < HOUR_MS) {
+    return t('common.duration.minutesSecondsCompact', {
+      minutes: Math.floor(total / MINUTE_MS),
+      seconds: Math.floor((total % MINUTE_MS) / SECOND_MS),
+    });
+  }
+  return t('common.duration.hoursMinutesCompact', {
+    hours: Math.floor(total / HOUR_MS),
+    minutes: Math.floor((total % HOUR_MS) / MINUTE_MS),
+  });
+};
diff --git a/packages/ui/src/components/session/sidebar/DOCUMENTATION.md b/packages/ui/src/components/session/sidebar/DOCUMENTATION.md
index becce78f..4033b4b8 100644
--- a/packages/ui/src/components/session/sidebar/DOCUMENTATION.md
+++ b/packages/ui/src/components/session/sidebar/DOCUMENTATION.md
@@ -6,6 +6,7 @@
 - Layout (web/desktop): top navigation (`SidebarNav`: New session, Scheduled, Multi-run, Archive), then the `recent` zone, then one zone per project with a **flat** session list. There is no rendered worktree grouping level.
 - **Two grouping display modes** (`useSessionDisplayStore.sessionGroupingMode`, toggled in the view dropdown): `'by-worktree'` (default) renders the worktree-grouped `sectionsForRender` with slim PR-aware branch sub-headers inside each project zone; `'flat'` renders `flatSectionsForRender` — one merged non-archived group per project (`id: 'flat'`, `folderScopes` listing every contributing scope) with per-row branch markers. Both derive from the same `projectSections` data layer, which alone feeds bootstrap demand planning and PR polling.
 - When sticky zone headers are enabled, project headers are sticky "zone" bands (`SortableProjectItem`); on a vibrant desktop the scrolling content fades behind an unmasked, non-interactive copy of the stuck icon/title without painting a background. The transparent fade zone blocks interaction with obscured rows. The `recent` section uses the same overlay while it is the leading sticky header. Collapsed projects show an aggregated busy/unseen indicator (`ProjectAggregateStatusIndicator`), derived from the live status index and notification store scoped to the project's directories.
+- **Activity is a dot plus a counter, never a spinner.** The row's left gutter shows a static dot — primary while the session runs (`busy`/`retry`), info while it is unread — and the metadata slot on the right swaps the goal/branch/date group for the elapsed time of the turn (`SessionActivityDuration`, ticking once per second). The readout takes the dot's color in each state — primary while running, info once it is waiting to be read — so the pair reads as one indicator. A running spinner repainted a composited layer per row every frame for the whole turn; the counter conveys the same "something is happening" at 1 fps. The counter follows the unread marker's lifetime exactly: it survives the turn ending, disappears when the session is read, and never lingers on the session being watched (which is marked read as it goes idle). Aggregate indicators for collapsed groups, folders, and projects show the dot only — a group may hold several running turns, so a single counter would have nothing to count. The same treatment applies to the mobile sessions sheet and session switcher rows. The worktree-move indicator stays a spinner: it marks a short user-initiated operation, not a session state.
 - Session rows have a single layout (former `minimal`); the `default`/`minimal` display mode was removed (`session-display-mode` store v4 migration drops the key). Rows show an inline branch label (from `node.worktree` or recent's `secondaryMeta`) when the session lives outside the project root, and bold titles while unread.
 - Folders render **flat** after the loose sessions: nested folders keep `parentId` in the data model but display at one level with a "Parent / Child" path label (`SessionFolderItem.displayName`); collapsing a folder hides its whole subtree. Folder actions resolve their owning scope per folder entry (folders from multiple worktree scopes can coexist under one project).
 - Archived sessions are not shown in the web/desktop sidebar; the Archive page (`ArchiveView`, `useUIStore.isArchivePageOpen`) replaces the old toggle. VS Code keeps inline archived buckets behind `showArchivedSessions` (compact webview has no page surfaces). Restore (unarchive) is available per session (row context menu, Archive page row) and in bulk (selection bar) and writes `time.archived = 0` — the server cannot clear the field over HTTP, so the global session cache splits active/archived client-side (see "Restore (unarchive) contract" in `sync/DOCUMENTATION.md`).
@@ -32,6 +33,7 @@
 - `SidebarProjectsList.tsx`: Main scrollable renderer for project zones and their flat/archived groups plus empty/search states; owns project drag-to-reorder.
 - `SessionGroupSection.tsx`: Renders one flat (or archived) group: sessions first, then flat folder entries with path labels, show-more batching, and explicit loading/error/retry state for empty groups. Archived buckets (VS Code) virtualize past 50 rows.
 - `SessionNodeItem.tsx`: Renders one session row/tree node with a single-line layout, inline branch label, indicators, menu actions, and nested children. Rows do not initiate directory bootstrap on mount.
+- `collapsedActivityIndicator.tsx`: Aggregate busy/unseen dot for collapsed groups and folders.
 - `ConfirmDialogs.tsx`: Shared confirm dialog wrappers for session delete and folder delete flows.
 - `sortableItems.tsx`: DnD sortable wrapper for project ordering plus the sticky zone-band project header and its action affordances.
 - `sessionFolderDnd.tsx`: Folder/session DnD scope and wrappers for dropping/moving sessions into folders.
diff --git a/packages/ui/src/components/session/sidebar/SessionNodeItem.tsx b/packages/ui/src/components/session/sidebar/SessionNodeItem.tsx
index ee143afd..6521feba 100644
--- a/packages/ui/src/components/session/sidebar/SessionNodeItem.tsx
+++ b/packages/ui/src/components/session/sidebar/SessionNodeItem.tsx
@@ -34,6 +34,8 @@ import { useProjectsStore } from '@/stores/useProjectsStore';
 import { useSessionDisplayStore } from '@/stores/useSessionDisplayStore';
 import { getGitHubPrStatusKey, usePrVisualSummary } from '@/stores/useGitHubPrStatusStore';
 import { useSessionUnseenCount } from '@/sync/notification-store';
+import { useHasSessionActivityDuration } from '@/sync/session-activity-timing';
+import { SessionActivityDuration } from '@/components/session/SessionActivityDuration';
 import { useSessionMultiSelectStore } from '@/stores/useSessionMultiSelectStore';
 import { useI18n } from '@/lib/i18n';
 import { useShiftKeyHeld } from '@/hooks/useShiftKeyHeld';
@@ -443,6 +445,11 @@ function SessionNodeItemComponent(props: Props): React.ReactNode {
     React.useCallback((state) => Boolean(state.sessionMemoryState.get(viewportSessionKey(session.id))?.isZombie), [session.id]),
   );
   const sessionStatus = useGlobalSessionStatus(session.id);
+  const statusType = sessionStatus?.type ?? 'idle';
+  const isStreaming = statusType === 'busy' || statusType === 'retry';
+  // Read as a boolean, not as the value: the row must not re-render on every
+  // tick of the counter it only decides to mount.
+  const hasActivityDuration = useHasSessionActivityDuration(session.id, isStreaming);
   const isMovingToWorktree = useIsSessionWorktreeMovePending(session.id);
   const sessionPermissions = useSessionPermissions(session.id, sessionDirectory ?? undefined, { bootstrap: false });
   const sessionGoal = getSessionGoal(resolvedSession);
@@ -668,26 +675,28 @@ function SessionNodeItemComponent(props: Props): React.ReactNode {
     );
   }
 
-  const statusType = sessionStatus?.type ?? 'idle';
-  const isStreaming = statusType === 'busy' || statusType === 'retry';
   const pendingPermissionCount = sessionPermissions.length;
   const showUnreadStatus = !isMovingToWorktree && !isStreaming && needsAttention && !isActive;
   const showStatusMarker = isStreaming || showUnreadStatus;
-  const statusMarkerContent = isStreaming
-    ? (
-        <Icon
-          name="loader-4"
-          className="h-3 w-3 animate-spin text-primary"
-          aria-label={t('sessions.sidebar.session.status.active')}
-        />
-      )
-    : (
-        <span
-          className="h-1.5 w-1.5 rounded-full bg-[var(--status-info)]"
-          aria-label={t('sessions.sidebar.session.status.unread')}
-          title={t('sessions.sidebar.session.status.unread')}
-        />
-      );
+  // Both states are the same static dot; only the color separates "running"
+  // from "unread". The elapsed-turn readout on the right carries the motion
+  // that a spinner used to, at one repaint per second instead of per frame.
+  const statusMarkerLabel = isStreaming
+    ? t('sessions.sidebar.session.status.active')
+    : t('sessions.sidebar.session.status.unread');
+  const statusMarkerContent = (
+    <span
+      className={cn(
+        'h-1.5 w-1.5 rounded-full',
+        isStreaming ? 'bg-primary' : 'bg-[var(--status-info)]',
+      )}
+      aria-label={statusMarkerLabel}
+      title={statusMarkerLabel}
+    />
+  );
+  // The settled duration lives exactly as long as the unread marker does, so a
+  // session read (or watched) while it finishes never keeps a stale total.
+  const showActivityDuration = (isStreaming || showUnreadStatus) && hasActivityDuration;
   const hideLeadingIndicatorOnHover = !alwaysShowActions && hasChildren && (isMovingToWorktree || showStatusMarker || isPinnedSession);
   const showPinnedMarker = isPinnedSession && !isMovingToWorktree && !showStatusMarker;
   const pinnedMarkerContent = (
@@ -1224,21 +1233,31 @@ function SessionNodeItemComponent(props: Props): React.ReactNode {
                           would reflow the truncated title and cause a micro
                           horizontal shift when the status flips. */}
                       <div className={cn('block min-w-0 flex-1 truncate typography-ui-label font-normal', isActive ? 'text-primary' : needsAttention ? 'text-foreground' : 'text-foreground/80')}>{renderHighlightedText(sessionTitle, normalizedSessionSearchQuery)}</div>
+                      {/* While a turn runs (and until its result is read) the
+                          elapsed counter takes over this slot from the usual
+                          goal/branch/date metadata, which stays one hover or
+                          one read away. */}
                       {alwaysShowActions ? (
                         // Touch runtimes have no hover tooltip, so the compact
                         // date stays inline there.
                         <span className="ml-2 inline-flex flex-shrink-0 items-center gap-1 text-[0.72rem] text-muted-foreground/75">
-                          {sessionGoalGlyph}
-                          {showInlineBranchMarker ? (
-                            <Icon
-                              name="git-branch"
-                              className={cn('h-3 w-3', !prIconColor && 'text-muted-foreground/60')}
-                              style={prIconColor ? { color: prIconColor } : undefined}
-                            />
-                          ) : null}
-                          {sessionCompactUpdatedLabel}
+                          {showActivityDuration ? (
+                            <SessionActivityDuration sessionId={session.id} running={isStreaming} />
+                          ) : (
+                            <>
+                              {sessionGoalGlyph}
+                              {showInlineBranchMarker ? (
+                                <Icon
+                                  name="git-branch"
+                                  className={cn('h-3 w-3', !prIconColor && 'text-muted-foreground/60')}
+                                  style={prIconColor ? { color: prIconColor } : undefined}
+                                />
+                              ) : null}
+                              {sessionCompactUpdatedLabel}
+                            </>
+                          )}
                         </span>
-                      ) : (sessionGoalGlyph || showInlineBranchMarker) ? (
+                      ) : (showActivityDuration || sessionGoalGlyph || showInlineBranchMarker) ? (
                         <div className="relative ml-1 flex h-4 flex-shrink-0 items-center justify-end">
                           <span className={cn(
                             'inline-flex items-center gap-1 whitespace-nowrap text-right transition-opacity duration-150',
@@ -1246,14 +1265,24 @@ function SessionNodeItemComponent(props: Props): React.ReactNode {
                               ? 'opacity-0'
                               : hideOnHoverClass,
                           )}>
-                            {sessionGoalGlyph}
-                            {showInlineBranchMarker ? (
-                              <Icon
-                                name="git-branch"
-                                className={cn('h-3 w-3', !prIconColor && 'text-muted-foreground/60')}
-                                style={prIconColor ? { color: prIconColor } : undefined}
+                            {showActivityDuration ? (
+                              <SessionActivityDuration
+                                sessionId={session.id}
+                                running={isStreaming}
+                                className="text-[0.72rem]"
                               />
-                            ) : null}
+                            ) : (
+                              <>
+                                {sessionGoalGlyph}
+                                {showInlineBranchMarker ? (
+                                  <Icon
+                                    name="git-branch"
+                                    className={cn('h-3 w-3', !prIconColor && 'text-muted-foreground/60')}
+                                    style={prIconColor ? { color: prIconColor } : undefined}
+                                  />
+                                ) : null}
+                              </>
+                            )}
                           </span>
                         </div>
                       ) : null}
diff --git a/packages/ui/src/components/session/sidebar/collapsedActivityIndicator.tsx b/packages/ui/src/components/session/sidebar/collapsedActivityIndicator.tsx
index 4d3cfaba..d5cd2a50 100644
--- a/packages/ui/src/components/session/sidebar/collapsedActivityIndicator.tsx
+++ b/packages/ui/src/components/session/sidebar/collapsedActivityIndicator.tsx
@@ -1,5 +1,4 @@
 import React from 'react';
-import { Icon } from '@/components/icon/Icon';
 import { cn } from '@/lib/utils';
 import type { CollapsedActivityState } from './collapsedActivityState';
 
@@ -15,21 +14,13 @@ export function CollapsedActivityIndicator({
   className?: string;
 }): React.ReactNode {
   const label = state === 'active' ? activeLabel : unreadLabel;
-  if (state === 'active') {
-    return (
-      <Icon
-        name="loader-4"
-        className={cn('h-3 w-3 shrink-0 animate-spin text-primary', className)}
-        aria-label={label}
-      />
-    );
-  }
-
+  // Aggregate rows carry the dot only; the elapsed counter is per session and
+  // has no meaning for a collapsed group that may hold several running turns.
   return (
     <span
       className={cn(
         'h-1.5 w-1.5 shrink-0 rounded-full',
-        'bg-[var(--status-info)]',
+        state === 'active' ? 'bg-primary' : 'bg-[var(--status-info)]',
         className,
       )}
       aria-label={label}
diff --git a/packages/ui/src/components/chat/message/parts/useDurationTicker.ts b/packages/ui/src/hooks/useDurationTicker.ts
similarity index 89%
rename from packages/ui/src/components/chat/message/parts/useDurationTicker.ts
rename to packages/ui/src/hooks/useDurationTicker.ts
index 3fdfe938..3bb0bb13 100644
--- a/packages/ui/src/components/chat/message/parts/useDurationTicker.ts
+++ b/packages/ui/src/hooks/useDurationTicker.ts
@@ -1,3 +1,7 @@
+// Shared wall-clock ticker for live duration readouts (tool runtimes, session
+// activity counters). Subscribers of the same interval share one timer and one
+// `now`, so N live rows cost one interval rather than N.
+
 import React from 'react';
 
 type Subscriber = (now: number) => void;
diff --git a/packages/ui/src/lib/i18n/messages/de.ts b/packages/ui/src/lib/i18n/messages/de.ts
index a169280f..57a22de2 100644
--- a/packages/ui/src/lib/i18n/messages/de.ts
+++ b/packages/ui/src/lib/i18n/messages/de.ts
@@ -473,6 +473,8 @@ export const dict = {
   'sessions.sidebar.session.status.unread': 'Ungelesene Updates',
   'sessions.sidebar.session.status.pinned': 'Angeheftete Sitzung',
   'sessions.sidebar.session.status.permissionRequired': 'Berechtigung erforderlich',
+  'sessions.sidebar.session.status.activeFor': 'Seit {duration} aktiv',
+  'sessions.sidebar.session.status.lastTurnDuration': 'Letzter Durchlauf dauerte {duration}',
   'sessions.sidebar.session.subsessions.collapse': 'Untersitzungen einklappen',
   'sessions.sidebar.session.subsessions.expand': 'Untersitzungen ausklappen',
   'sessions.sidebar.dialogs.deleteSession.title': 'Sitzung löschen?',
@@ -2728,6 +2730,9 @@ export const dict = {
   'common.relative.daysAgoCompact': '{count}d her',
   'common.relative.weeksAgoCompact': '{count}w her',
   'common.relative.yearsAgoCompact': '{count}y her',
+  'common.duration.secondsCompact': '{seconds}s',
+  'common.duration.minutesSecondsCompact': '{minutes}m {seconds}s',
+  'common.duration.hoursMinutesCompact': '{hours}h {minutes}m',
   'contextFileOpen.failure.tooLarge': 'Datei ist zu groß zum Öffnen (>{count} Zeilen)',
   'contextFileOpen.failure.missing': 'Datei nicht gefunden',
   'contextFileOpen.failure.unreadable': 'Fehler beim Öffnen der Datei',
diff --git a/packages/ui/src/lib/i18n/messages/en.ts b/packages/ui/src/lib/i18n/messages/en.ts
index 6d2e76a5..c77d6a07 100644
--- a/packages/ui/src/lib/i18n/messages/en.ts
+++ b/packages/ui/src/lib/i18n/messages/en.ts
@@ -530,6 +530,8 @@ export const dict = {
   'sessions.sidebar.session.status.pinned': 'Pinned session',
   'sessions.sidebar.session.status.movingToWorktree': 'Moving session to a new worktree',
   'sessions.sidebar.session.status.permissionRequired': 'Permission required',
+  'sessions.sidebar.session.status.activeFor': 'Active for {duration}',
+  'sessions.sidebar.session.status.lastTurnDuration': 'Last turn took {duration}',
   'sessions.sidebar.session.subsessions.collapse': 'Collapse subsessions',
   'sessions.sidebar.session.subsessions.expand': 'Expand subsessions',
   'sessions.sidebar.dialogs.deleteSession.title': 'Delete session?',
@@ -2900,6 +2902,9 @@ export const dict = {
   'common.relative.daysAgoCompact': '{count}d ago',
   'common.relative.weeksAgoCompact': '{count}w ago',
   'common.relative.yearsAgoCompact': '{count}y ago',
+  'common.duration.secondsCompact': '{seconds}s',
+  'common.duration.minutesSecondsCompact': '{minutes}m {seconds}s',
+  'common.duration.hoursMinutesCompact': '{hours}h {minutes}m',
   'contextFileOpen.failure.tooLarge': 'File is too large to open (>{count} lines)',
   'contextFileOpen.failure.missing': 'File not found',
   'contextFileOpen.failure.unreadable': 'Failed to open file',
diff --git a/packages/ui/src/lib/i18n/messages/es.ts b/packages/ui/src/lib/i18n/messages/es.ts
index 18a8b9ed..72985914 100644
--- a/packages/ui/src/lib/i18n/messages/es.ts
+++ b/packages/ui/src/lib/i18n/messages/es.ts
@@ -531,6 +531,8 @@ export const dict: Record<I18nKey, string> = {
   "sessions.sidebar.session.status.pinned": "Sesión anclada",
   "sessions.sidebar.session.status.movingToWorktree": "Moviendo la sesión a un worktree nuevo",
   "sessions.sidebar.session.status.permissionRequired": "Permiso requerido",
+  "sessions.sidebar.session.status.activeFor": "Activa desde hace {duration}",
+  "sessions.sidebar.session.status.lastTurnDuration": "El último turno duró {duration}",
   "sessions.sidebar.session.subsessions.collapse": "Colapsar subsesiones",
   "sessions.sidebar.session.subsessions.expand": "Expandir subsesiones",
   "sessions.sidebar.dialogs.deleteSession.title": "¿Eliminar sesión?",
@@ -2901,6 +2903,9 @@ export const dict: Record<I18nKey, string> = {
   "common.relative.daysAgoCompact": "{count}d ago",
   "common.relative.weeksAgoCompact": "{count}w ago",
   "common.relative.yearsAgoCompact": "{count}y ago",
+  "common.duration.secondsCompact": "{seconds}s",
+  "common.duration.minutesSecondsCompact": "{minutes}m {seconds}s",
+  "common.duration.hoursMinutesCompact": "{hours}h {minutes}m",
   "contextFileOpen.failure.tooLarge": "File is too large to open (>{count} lines)",
   "contextFileOpen.failure.missing": "File not found",
   "contextFileOpen.failure.unreadable": "Failed to open file",
diff --git a/packages/ui/src/lib/i18n/messages/fr.ts b/packages/ui/src/lib/i18n/messages/fr.ts
index a387f1c7..986a4cd4 100644
--- a/packages/ui/src/lib/i18n/messages/fr.ts
+++ b/packages/ui/src/lib/i18n/messages/fr.ts
@@ -366,6 +366,8 @@ export const dict = {
   'sessions.sidebar.session.status.pinned': 'Session épinglée',
   'sessions.sidebar.session.status.movingToWorktree': 'Déplacement de la session vers un nouveau worktree',
   'sessions.sidebar.session.status.permissionRequired': 'Autorisation requise',
+  'sessions.sidebar.session.status.activeFor': 'Active depuis {duration}',
+  'sessions.sidebar.session.status.lastTurnDuration': 'Le dernier tour a duré {duration}',
   'sessions.sidebar.session.subsessions.collapse': 'Réduire les sous-sessions',
   'sessions.sidebar.session.subsessions.expand': 'Développer les sous-sessions',
   'sessions.sidebar.dialogs.deleteSession.title': 'Supprimer la session ?',
@@ -2648,6 +2650,9 @@ export const dict = {
   'common.relative.daysAgoCompact': '{count} j',
   'common.relative.weeksAgoCompact': '{count} sem',
   'common.relative.yearsAgoCompact': '{count} a',
+  'common.duration.secondsCompact': '{seconds}s',
+  'common.duration.minutesSecondsCompact': '{minutes}m {seconds}s',
+  'common.duration.hoursMinutesCompact': '{hours}h {minutes}m',
   'contextFileOpen.failure.tooLarge': 'Le fichier est trop volumineux pour être ouvert (> {count} lignes)',
   'contextFileOpen.failure.missing': 'Fichier introuvable',
   'contextFileOpen.failure.unreadable': 'Impossible d’ouvrir le fichier',
diff --git a/packages/ui/src/lib/i18n/messages/ja.ts b/packages/ui/src/lib/i18n/messages/ja.ts
index 68a4fb7a..0f4da4e7 100644
--- a/packages/ui/src/lib/i18n/messages/ja.ts
+++ b/packages/ui/src/lib/i18n/messages/ja.ts
@@ -531,6 +531,8 @@ export const dict: Record<I18nKey, string> = {
   'sessions.sidebar.session.status.pinned': 'ピン留めされたセッション',
   'sessions.sidebar.session.status.movingToWorktree': 'セッションを新しいworktreeへ移動中',
   'sessions.sidebar.session.status.permissionRequired': '権限が必要です',
+  'sessions.sidebar.session.status.activeFor': 'アクティブ時間 {duration}',
+  'sessions.sidebar.session.status.lastTurnDuration': '前回のターンの所要時間 {duration}',
   'sessions.sidebar.session.subsessions.collapse': 'サブセッションを折りたたむ',
   'sessions.sidebar.session.subsessions.expand': 'サブセッションを展開',
   'sessions.sidebar.dialogs.deleteSession.title': 'セッションを削除しますか？',
@@ -2896,6 +2898,9 @@ export const dict: Record<I18nKey, string> = {
   'common.relative.daysAgoCompact': '{count}日前',
   'common.relative.weeksAgoCompact': '{count}週前',
   'common.relative.yearsAgoCompact': '{count}年前',
+  'common.duration.secondsCompact': '{seconds}秒',
+  'common.duration.minutesSecondsCompact': '{minutes}分{seconds}秒',
+  'common.duration.hoursMinutesCompact': '{hours}時間{minutes}分',
   'contextFileOpen.failure.tooLarge': 'ファイルが大きすぎて開けません（>{count}行）',
   'contextFileOpen.failure.missing': 'ファイルが見つかりません',
   'contextFileOpen.failure.unreadable': 'ファイルを開けませんでした',
diff --git a/packages/ui/src/lib/i18n/messages/ko.ts b/packages/ui/src/lib/i18n/messages/ko.ts
index 03532bc5..0f09fba2 100644
--- a/packages/ui/src/lib/i18n/messages/ko.ts
+++ b/packages/ui/src/lib/i18n/messages/ko.ts
@@ -531,6 +531,8 @@ export const dict: Record<I18nKey, string> = {
   'sessions.sidebar.session.status.pinned': '고정된 세션',
   'sessions.sidebar.session.status.movingToWorktree': '세션을 새 worktree로 이동하는 중',
   'sessions.sidebar.session.status.permissionRequired': '권한 필요',
+  'sessions.sidebar.session.status.activeFor': '{duration} 동안 활성 상태',
+  'sessions.sidebar.session.status.lastTurnDuration': '마지막 턴 소요 시간 {duration}',
   'sessions.sidebar.session.subsessions.collapse': '하위 세션 접기',
   'sessions.sidebar.session.subsessions.expand': '하위 세션 펼치기',
   'sessions.sidebar.dialogs.deleteSession.title': '세션 삭제?',
@@ -2900,6 +2902,9 @@ export const dict: Record<I18nKey, string> = {
   'common.relative.daysAgoCompact': '{count}d ago',
   'common.relative.weeksAgoCompact': '{count}w ago',
   'common.relative.yearsAgoCompact': '{count}y ago',
+  'common.duration.secondsCompact': '{seconds}초',
+  'common.duration.minutesSecondsCompact': '{minutes}분 {seconds}초',
+  'common.duration.hoursMinutesCompact': '{hours}시간 {minutes}분',
   'contextFileOpen.failure.tooLarge': 'File is too large to open (>{count} lines)',
   'contextFileOpen.failure.missing': 'File not found',
   'contextFileOpen.failure.unreadable': 'Failed to open file',
diff --git a/packages/ui/src/lib/i18n/messages/pl.ts b/packages/ui/src/lib/i18n/messages/pl.ts
index 245cbc5f..12f727b1 100644
--- a/packages/ui/src/lib/i18n/messages/pl.ts
+++ b/packages/ui/src/lib/i18n/messages/pl.ts
@@ -531,6 +531,8 @@ export const dict: Record<I18nKey, string> = {
   'sessions.sidebar.session.status.pinned': 'Przypięta sesja',
   'sessions.sidebar.session.status.movingToWorktree': 'Przenoszenie sesji do nowego worktree',
   'sessions.sidebar.session.status.permissionRequired': 'Wymagane uprawnienie',
+  'sessions.sidebar.session.status.activeFor': 'Aktywna od {duration}',
+  'sessions.sidebar.session.status.lastTurnDuration': 'Ostatnia tura trwała {duration}',
   'sessions.sidebar.session.subsessions.collapse': 'Zwiń pod-sesje',
   'sessions.sidebar.session.subsessions.expand': 'Rozwiń pod-sesje',
   'sessions.sidebar.dialogs.deleteSession.title': 'Usunąć sesję?',
@@ -2917,6 +2919,9 @@ export const dict: Record<I18nKey, string> = {
   'common.relative.daysAgoCompact': '{count}d ago',
   'common.relative.weeksAgoCompact': '{count}w ago',
   'common.relative.yearsAgoCompact': '{count}y ago',
+  'common.duration.secondsCompact': '{seconds}s',
+  'common.duration.minutesSecondsCompact': '{minutes}m {seconds}s',
+  'common.duration.hoursMinutesCompact': '{hours}h {minutes}m',
   'contextFileOpen.failure.tooLarge': 'File is too large to open (>{count} lines)',
   'contextFileOpen.failure.missing': 'File not found',
   'contextFileOpen.failure.unreadable': 'Failed to open file',
diff --git a/packages/ui/src/lib/i18n/messages/pt-BR.ts b/packages/ui/src/lib/i18n/messages/pt-BR.ts
index 42098a94..10dd7709 100644
--- a/packages/ui/src/lib/i18n/messages/pt-BR.ts
+++ b/packages/ui/src/lib/i18n/messages/pt-BR.ts
@@ -531,6 +531,8 @@ export const dict: Record<I18nKey, string> = {
   "sessions.sidebar.session.status.pinned": "Sessão fixada",
   "sessions.sidebar.session.status.movingToWorktree": "Movendo a sessão para um novo worktree",
   "sessions.sidebar.session.status.permissionRequired": "Permissão obrigatória",
+  "sessions.sidebar.session.status.activeFor": "Ativa há {duration}",
+  "sessions.sidebar.session.status.lastTurnDuration": "O último turno levou {duration}",
   "sessions.sidebar.session.subsessions.collapse": "Recolher subsessões",
   "sessions.sidebar.session.subsessions.expand": "Expandir subsessões",
   "sessions.sidebar.dialogs.deleteSession.title": "Excluir sessão?",
@@ -2901,6 +2903,9 @@ export const dict: Record<I18nKey, string> = {
   "common.relative.daysAgoCompact": "{count}d ago",
   "common.relative.weeksAgoCompact": "{count}w ago",
   "common.relative.yearsAgoCompact": "{count}y ago",
+  "common.duration.secondsCompact": "{seconds}s",
+  "common.duration.minutesSecondsCompact": "{minutes}m {seconds}s",
+  "common.duration.hoursMinutesCompact": "{hours}h {minutes}m",
   "contextFileOpen.failure.tooLarge": "File is too large to open (>{count} lines)",
   "contextFileOpen.failure.missing": "File not found",
   "contextFileOpen.failure.unreadable": "Failed to open file",
diff --git a/packages/ui/src/lib/i18n/messages/uk.ts b/packages/ui/src/lib/i18n/messages/uk.ts
index 1143d4c0..dd52bcb9 100644
--- a/packages/ui/src/lib/i18n/messages/uk.ts
+++ b/packages/ui/src/lib/i18n/messages/uk.ts
@@ -531,6 +531,8 @@ export const dict: Record<I18nKey, string> = {
   "sessions.sidebar.session.status.pinned": "Закріплений сесія",
   "sessions.sidebar.session.status.movingToWorktree": "Перенесення сесії в новий worktree",
   "sessions.sidebar.session.status.permissionRequired": "Потрібен дозвіл",
+  "sessions.sidebar.session.status.activeFor": "Активна вже {duration}",
+  "sessions.sidebar.session.status.lastTurnDuration": "Останній хід тривав {duration}",
   "sessions.sidebar.session.subsessions.collapse": "Згорнути підсесії",
   "sessions.sidebar.session.subsessions.expand": "Розгорнути підсесії",
   "sessions.sidebar.dialogs.deleteSession.title": "Видалити сесія?",
@@ -2901,6 +2903,9 @@ export const dict: Record<I18nKey, string> = {
   "common.relative.daysAgoCompact": "{count}d ago",
   "common.relative.weeksAgoCompact": "{count}w ago",
   "common.relative.yearsAgoCompact": "{count}y ago",
+  "common.duration.secondsCompact": "{seconds}с",
+  "common.duration.minutesSecondsCompact": "{minutes}хв {seconds}с",
+  "common.duration.hoursMinutesCompact": "{hours}год {minutes}хв",
   "contextFileOpen.failure.tooLarge": "File is too large to open (>{count} lines)",
   "contextFileOpen.failure.missing": "File not found",
   "contextFileOpen.failure.unreadable": "Failed to open file",
diff --git a/packages/ui/src/lib/i18n/messages/zh-CN.ts b/packages/ui/src/lib/i18n/messages/zh-CN.ts
index 7e9fa6c9..35de2c9c 100644
--- a/packages/ui/src/lib/i18n/messages/zh-CN.ts
+++ b/packages/ui/src/lib/i18n/messages/zh-CN.ts
@@ -531,6 +531,8 @@ export const dict: Record<I18nKey, string> = {
   'sessions.sidebar.session.status.pinned': '已置顶会话',
   'sessions.sidebar.session.status.movingToWorktree': '正在将会话移至新工作树',
   'sessions.sidebar.session.status.permissionRequired': '需要权限',
+  'sessions.sidebar.session.status.activeFor': '已活动 {duration}',
+  'sessions.sidebar.session.status.lastTurnDuration': '上一轮耗时 {duration}',
   'sessions.sidebar.session.subsessions.collapse': '折叠子会话',
   'sessions.sidebar.session.subsessions.expand': '展开子会话',
   'sessions.sidebar.dialogs.deleteSession.title': '删除会话？',
@@ -2901,6 +2903,9 @@ export const dict: Record<I18nKey, string> = {
   'common.relative.daysAgoCompact': '{count}d ago',
   'common.relative.weeksAgoCompact': '{count}w ago',
   'common.relative.yearsAgoCompact': '{count}y ago',
+  'common.duration.secondsCompact': '{seconds}秒',
+  'common.duration.minutesSecondsCompact': '{minutes}分{seconds}秒',
+  'common.duration.hoursMinutesCompact': '{hours}小时{minutes}分',
   'contextFileOpen.failure.tooLarge': 'File is too large to open (>{count} lines)',
   'contextFileOpen.failure.missing': 'File not found',
   'contextFileOpen.failure.unreadable': 'Failed to open file',
diff --git a/packages/ui/src/lib/i18n/messages/zh-TW.ts b/packages/ui/src/lib/i18n/messages/zh-TW.ts
index 35e3389d..6641606b 100644
--- a/packages/ui/src/lib/i18n/messages/zh-TW.ts
+++ b/packages/ui/src/lib/i18n/messages/zh-TW.ts
@@ -544,6 +544,8 @@ export const dict: Record<I18nKey, string> = {
   'sessions.sidebar.session.status.pinned': '已釘選會話',
   'sessions.sidebar.session.status.movingToWorktree': '正在將會話移至新工作樹',
   'sessions.sidebar.session.status.permissionRequired': '需要權限',
+  'sessions.sidebar.session.status.activeFor': '已活動 {duration}',
+  'sessions.sidebar.session.status.lastTurnDuration': '上一輪耗時 {duration}',
   'sessions.sidebar.session.subsessions.collapse': '摺疊子會話',
   'sessions.sidebar.session.subsessions.expand': '展開子會話',
   'sessions.sidebar.dialogs.deleteSession.title': '刪除會話？',
@@ -2900,6 +2902,9 @@ export const dict: Record<I18nKey, string> = {
   'common.relative.daysAgoCompact': '{count}d ago',
   'common.relative.weeksAgoCompact': '{count}w ago',
   'common.relative.yearsAgoCompact': '{count}y ago',
+  'common.duration.secondsCompact': '{seconds}秒',
+  'common.duration.minutesSecondsCompact': '{minutes}分{seconds}秒',
+  'common.duration.hoursMinutesCompact': '{hours}小時{minutes}分',
   'contextFileOpen.failure.tooLarge': 'File is too large to open (>{count} lines)',
   'contextFileOpen.failure.missing': 'File not found',
   'contextFileOpen.failure.unreadable': 'Failed to open file',
diff --git a/packages/ui/src/sync/DOCUMENTATION.md b/packages/ui/src/sync/DOCUMENTATION.md
index cc9b4abb..5699fc93 100644
--- a/packages/ui/src/sync/DOCUMENTATION.md
+++ b/packages/ui/src/sync/DOCUMENTATION.md
@@ -45,6 +45,7 @@ So:
 | `SessionMessageLoader` | Initial message loading, pagination, prefetch, retries, load state, and optimistic reconciliation | One runtime, directory, and session ID |
 | `global-session-status.ts` | Incremental non-idle session status index reconciled from events and authoritative directory snapshots | All known directories in the active runtime |
 | `session-ordering.ts` | Ephemeral lifecycle rank used by every user-visible session list | All known sessions in the active runtime |
+| `session-activity-timing.ts` | Elapsed time of the running turn and of the turn that just finished, plus the persisted starts that survive a reload | All known sessions in the active runtime |
 | `session-ui-store.ts` | Session selection, draft lifecycle, abort prompts, worktree metadata, SDK-facing action entrypoints | App UI state |
 | `useGlobalSessionsStore.ts` | Global active sessions, global archived sessions, `sessionsByDirectory` | All opened project/worktree session lists |
 | `viewport-store.ts` | Scroll anchors, session memory, loading indicators | App UI state |
@@ -128,6 +129,16 @@ Cross-directory selectors subscribe to the narrow child-store field they aggrega
 
 Session display order is independent from streaming-frequency `time.updated` publications. `session-ordering.ts` promotes a session exactly when its authoritative activity phase crosses `settled` (`idle`/`error`) and `active` (`busy`/`retry`) in either direction. Repeated busy/retry or idle/error events are no-ops. The first authoritative status snapshot establishes a baseline without synthetic promotions; later snapshots reconcile missed transitions. Root sessions compare lifecycle rank only with other roots, while child sessions compare lifecycle rank only with siblings sharing the same `parentID`, so child activity never moves its root conversation. Pins remain the first ordering bucket. The timestamp/creation fallback is frozen when a session first participates in ordering, so later metadata-only updates cannot reorder it; creation time and ID provide deterministic ties. Runtime switches clear all phases, baselines, and ranks.
 
+`session-activity-timing.ts` measures how long a turn has been running, because `SessionStatus` carries no timestamps. It is driven from the same two write paths as `global-session-status.ts`, so a row can never count a turn that index calls idle. A session gains a start on its first `active` observation and keeps it across repeated busy/retry events; settling converts that start into a finished duration, which rows show only while the session is unread and which is therefore never persisted.
+
+Starts are persisted so a reload resumes the same count, but a persisted start is a lookup table and never a claim of activity. **Nothing in the protocol marks where a turn begins.** OpenCode calls `SessionStatus.set` with `busy` at every step of the agent loop and publishes an event each time, so a busy event means "still running", not "just started"; after a refresh one of those repeats normally beats the first status snapshot, so treating it as a turn boundary reset the counter on nearly every reload. Turn *ends* are marked — `session.idle` and `session.error` fire once, live, and retire the persisted record — while a snapshot that omits a session is not evidence of anything, since it may simply not see it yet.
+
+That leaves the case with no observable answer: a turn that ended, and another that began, entirely while the tab was gone. Two bounds stand in for the evidence the client cannot have. A liveness stamp sits beside the start — refreshed while the session is observed active, at most every 15s, and stamped precisely as the page hides (`pagehide`/`visibilitychange`/`freeze`, written immediately rather than through deferred storage so it cannot lose that race) — and is compared against this page's `performance.timeOrigin`, so the measure is how long the app was absent rather than how long bootstrap took; a 20-second startup must not spend the allowance. Records may only be adopted within 90s of load, after which they are discarded — a backstop for a runtime whose event stream is down and where snapshots are therefore the only signal. A runtime switch resets the module, since the previous instance's turns are not ours.
+
+Reconciliation walks the running turns and asks the snapshot whether it covers each one, rather than being handed everything the snapshot covers. Only a live start can settle, and there are a handful of those against a directory's hundreds of sessions, so the pass stays proportional to the timing work and allocates nothing per poll. Malformed, wrong-shaped, over-age, and future-dated entries are rejected on read. The payload is not runtime-scoped: records live for seconds and are keyed by instance-unique session IDs, whereas the runtime key is derived from injected globals and is not guaranteed stable across early startup — a read under a key the previous page never wrote to is indistinguishable from "no turn was running".
+
+**Only the stamp expires a persisted start.** A snapshot that covers a session without reporting it busy is not proof the turn ended: bootstrap fetches status and sessions in parallel and directory scopes resolve at different times, so a snapshot legitimately arrives before it can see a running session. Treating one of those as a settle deleted the start moments before the real busy snapshot arrived, which reset every counter to zero on reload. Settles therefore act only on sessions that already have a live start in this page session.
+
 The active-session watchdog in `sync-context.tsx` (per-directory status polls and child-session discovery lists) runs its network calls through the shared background-network gate in `@/lib/background-network`, alongside poll-shaped git reads, global session pages, and command/skill discovery. Background fan-out must stay under that gate so the browser's per-origin connection pool keeps free sockets for interactive traffic — an uncapped startup burst previously queued the first session-open message fetch for seconds.
 
 Imperative cross-directory session lookups use the cached ID index from `getAllSyncSessionMap()`. The index is rebuilt only when a child store's `state.session` reference changes; permission lineage checks must reuse it instead of rebuilding a full session map per call.
diff --git a/packages/ui/src/sync/global-session-status.ts b/packages/ui/src/sync/global-session-status.ts
index e2601bcf..ee458ade 100644
--- a/packages/ui/src/sync/global-session-status.ts
+++ b/packages/ui/src/sync/global-session-status.ts
@@ -6,6 +6,11 @@ import {
   reconcileSessionActivitySnapshot,
   removeSessionOrdering,
 } from './session-ordering';
+import {
+  observeSessionActivityTiming,
+  reconcileSessionActivityTiming,
+  removeSessionActivityTiming,
+} from './session-activity-timing';
 
 // Shared live busy/retry index for every directory. Global events update it
 // incrementally and authoritative directory snapshots reconcile it, so each
@@ -74,6 +79,8 @@ export const applyGlobalSessionStatusEvent = (directory: string, payload: Event)
         type === 'idle' ? { type: 'idle' } : { ...(props.status ?? {}), type } as SessionStatus,
       );
       observeSessionActivityEvent(props.sessionID, type === 'idle' ? 'settled' : 'active');
+      // `retry` is still a running turn, so the elapsed counter keeps going.
+      observeSessionActivityTiming(props.sessionID, type === 'idle' ? 'settled' : 'active');
       return;
     }
     case 'session.idle':
@@ -82,13 +89,17 @@ export const applyGlobalSessionStatusEvent = (directory: string, payload: Event)
       if (typeof props?.sessionID === 'string' && props.sessionID) {
         setStatus(props.sessionID, normalizeDirectory(directory), { type: 'idle' });
         observeSessionActivityEvent(props.sessionID, 'settled');
+        observeSessionActivityTiming(props.sessionID, 'settled');
       }
       return;
     }
     case 'session.deleted': {
       const props = payload.properties as { sessionID?: string; info?: { id?: string } } | undefined;
       const sessionId = props?.sessionID ?? props?.info?.id;
-      if (sessionId) removeSessionOrdering(sessionId);
+      if (sessionId) {
+        removeSessionOrdering(sessionId);
+        removeSessionActivityTiming(sessionId);
+      }
       return;
     }
     default:
@@ -108,10 +119,21 @@ export const applyGlobalSessionStatusSnapshot = (
 ): void => {
   const directory = normalizeDirectory(rawDirectory);
   const known = new Set(knownSessionIds ?? []);
-  const activeSessionIds = Object.entries(raw)
-    .filter(([, status]) => normalizeStatusType(status?.type) !== 'idle')
-    .map(([sessionId]) => sessionId);
+  // Built once as a set and shared by both consumers below; only non-idle
+  // sessions land here, so it stays small however long the directory's list is.
+  const activeSessionIds = new Set<string>();
+  for (const [sessionId, status] of Object.entries(raw)) {
+    if (normalizeStatusType(status?.type) !== 'idle') activeSessionIds.add(sessionId);
+  }
   reconcileSessionActivitySnapshot(activeSessionIds, known);
+  // Timing asks the coverage question instead of being handed a list: a snapshot
+  // authoritatively covers the caller's session list plus every id it reports
+  // itself, and only the handful of sessions actually being timed need an
+  // answer. Reuses the sets already built above, so this allocates nothing.
+  reconcileSessionActivityTiming(
+    activeSessionIds,
+    (sessionId) => known.has(sessionId) || sessionId in raw,
+  );
   useGlobalSessionStatusStore.setState((state) => {
     let changed = false;
     const next = new Map(state.statusById);
diff --git a/packages/ui/src/sync/session-activity-timing.test.ts b/packages/ui/src/sync/session-activity-timing.test.ts
new file mode 100644
index 00000000..cd01a4d4
--- /dev/null
+++ b/packages/ui/src/sync/session-activity-timing.test.ts
@@ -0,0 +1,310 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+
+import { getSafeStorage } from '@/stores/utils/safeStorage';
+import { applyGlobalSessionStatusSnapshot } from './global-session-status';
+import {
+  observeSessionActivityTiming,
+  reconcileSessionActivityTiming,
+  removeSessionActivityTiming,
+  resetSessionActivityTiming,
+  useSessionActivityTimingStore,
+} from './session-activity-timing';
+
+const STORAGE_KEY = 'oc.session-activity.v1';
+
+const startedAt = (sessionId: string): number | undefined =>
+  useSessionActivityTimingStore.getState().startedAt.get(sessionId);
+
+const settledMs = (sessionId: string): number | undefined =>
+  useSessionActivityTimingStore.getState().settledMs.get(sessionId);
+
+type PersistedStart = { start: number; seen: number };
+
+const readPersisted = (): Record<string, PersistedStart> | null => {
+  const raw = getSafeStorage().getItem(STORAGE_KEY);
+  return raw ? (JSON.parse(raw) as Record<string, PersistedStart>) : null;
+};
+
+/**
+ * Seed a previous page session's record, then simulate the reload.
+ * `loadedAgoMs` places this page's navigation start in the past, which is how a
+ * slow bootstrap or an expired adoption window is expressed.
+ */
+const seedReload = (payload: unknown, loadedAgoMs = 0): void => {
+  getSafeStorage().setItem(STORAGE_KEY, JSON.stringify(payload));
+  resetSessionActivityTiming({ pageLoadAt: Date.now() - loadedAgoMs });
+};
+
+/** A status snapshot: which sessions it reports busy, and which it covers. */
+const snapshot = (activeIds: string[], coveredIds: string[] = activeIds): void => {
+  const covered = new Set(coveredIds);
+  reconcileSessionActivityTiming(new Set(activeIds), (sessionId) => covered.has(sessionId));
+};
+
+/** A record for a turn that began `ageMs` ago and was alive until the reload. */
+const runningUntilReload = (ageMs: number, loadedAgoMs = 0, quietFor = 1_000): PersistedStart => ({
+  start: Date.now() - ageMs,
+  seen: Date.now() - loadedAgoMs - quietFor,
+});
+
+beforeEach(() => {
+  getSafeStorage().removeItem(STORAGE_KEY);
+  resetSessionActivityTiming();
+});
+
+afterEach(() => {
+  getSafeStorage().removeItem(STORAGE_KEY);
+  resetSessionActivityTiming();
+});
+
+describe('session activity timing', () => {
+  test('starts a turn on the first active observation and keeps it stable', () => {
+    observeSessionActivityTiming('ses_a', 'active');
+    const first = startedAt('ses_a');
+    expect(first).toBeGreaterThan(0);
+
+    // Repeated busy/retry status events must not restart the counter.
+    observeSessionActivityTiming('ses_a', 'active');
+    expect(startedAt('ses_a')).toBe(first);
+  });
+
+  test('settling converts the start into a duration', () => {
+    observeSessionActivityTiming('ses_a', 'active');
+    observeSessionActivityTiming('ses_a', 'settled');
+
+    expect(startedAt('ses_a')).toBe(undefined);
+    expect(settledMs('ses_a')).toBeGreaterThanOrEqual(0);
+  });
+
+  test('a new turn clears the previous settled duration', () => {
+    observeSessionActivityTiming('ses_a', 'active');
+    observeSessionActivityTiming('ses_a', 'settled');
+    expect(settledMs('ses_a')).toBeDefined();
+
+    observeSessionActivityTiming('ses_a', 'active');
+    expect(settledMs('ses_a')).toBe(undefined);
+    expect(startedAt('ses_a')).toBeDefined();
+  });
+
+  test('settling a session that was never observed active yields no duration', () => {
+    observeSessionActivityTiming('ses_a', 'settled');
+
+    expect(startedAt('ses_a')).toBe(undefined);
+    expect(settledMs('ses_a')).toBe(undefined);
+  });
+
+  test('snapshot reconciliation starts covered actives and settles the rest', () => {
+    observeSessionActivityTiming('ses_a', 'active');
+    observeSessionActivityTiming('ses_b', 'active');
+
+    snapshot(['ses_a'], ['ses_a', 'ses_b', 'ses_c']);
+
+    expect(startedAt('ses_a')).toBeDefined();
+    expect(startedAt('ses_b')).toBe(undefined);
+    expect(settledMs('ses_b')).toBeGreaterThanOrEqual(0);
+    // Never active, never covered by a start: nothing to report.
+    expect(settledMs('ses_c')).toBe(undefined);
+  });
+
+  test('a session outside the snapshot scope keeps running', () => {
+    observeSessionActivityTiming('ses_other_directory', 'active');
+    const start = startedAt('ses_other_directory');
+
+    snapshot([], ['ses_a']);
+
+    expect(startedAt('ses_other_directory')).toBe(start);
+  });
+
+  test('persists the start and a liveness stamp for a running turn', () => {
+    observeSessionActivityTiming('ses_a', 'active');
+
+    const persisted = readPersisted();
+    expect(persisted?.ses_a.start).toBe(startedAt('ses_a') as number);
+    expect(persisted?.ses_a.seen).toBeGreaterThanOrEqual(persisted?.ses_a.start as number);
+  });
+
+  test('clears the persisted record when the turn ends', () => {
+    observeSessionActivityTiming('ses_a', 'active');
+    observeSessionActivityTiming('ses_a', 'settled');
+
+    expect(readPersisted()).toBeNull();
+  });
+
+  test('resumes a persisted start when a status snapshot reports the session active', () => {
+    const record = runningUntilReload(90_000);
+    seedReload({ ses_a: record });
+
+    snapshot(['ses_a'], ['ses_a']);
+
+    expect(startedAt('ses_a')).toBe(record.start);
+  });
+
+  // Regression: the server re-publishes `session.status: busy` at every step of
+  // the agent loop, so after a reload one of those repeats normally arrives
+  // before the first status snapshot. Reading a busy event as "a turn just
+  // started" therefore reset the counter on almost every refresh.
+  test('resumes when a repeated busy event arrives before the first snapshot', () => {
+    const record = runningUntilReload(90_000);
+    seedReload({ ses_a: record });
+
+    observeSessionActivityTiming('ses_a', 'active');
+
+    expect(startedAt('ses_a')).toBe(record.start);
+  });
+
+  test('the turn after a resumed one still counts from zero', () => {
+    const record = runningUntilReload(90_000);
+    seedReload({ ses_a: record });
+
+    // Reload lands mid-turn: the snapshot resumes it…
+    snapshot(['ses_a'], ['ses_a']);
+    expect(startedAt('ses_a')).toBe(record.start);
+
+    // …it finishes, which retires the record, so the next turn starts fresh.
+    observeSessionActivityTiming('ses_a', 'settled');
+    const before = Date.now();
+    observeSessionActivityTiming('ses_a', 'active');
+
+    expect(startedAt('ses_a')).toBeGreaterThanOrEqual(before);
+  });
+
+  test('a live idle event retires the persisted record', () => {
+    const record = runningUntilReload(90_000);
+    seedReload({ ses_a: record });
+
+    // The turn ended while the tab was gone; the event arrives on reconnect.
+    observeSessionActivityTiming('ses_a', 'settled');
+    // A later snapshot must not resurrect the retired start.
+    const before = Date.now();
+    snapshot(['ses_a'], ['ses_a']);
+
+    expect(startedAt('ses_a')).toBeGreaterThanOrEqual(before);
+  });
+
+  // The absence is measured from navigation start, not from "now", so a slow
+  // bootstrap on a slow machine cannot spend the whole allowance before the
+  // first status snapshot arrives.
+  test('resumes even when bootstrap takes most of a minute', () => {
+    const loadedAgoMs = 45_000;
+    const record = runningUntilReload(300_000, loadedAgoMs);
+    seedReload({ ses_a: record }, loadedAgoMs);
+
+    snapshot(['ses_a'], ['ses_a']);
+
+    expect(startedAt('ses_a')).toBe(record.start);
+  });
+
+  test('does not adopt a record once the adoption window has passed', () => {
+    const loadedAgoMs = 5 * 60_000;
+    const record = runningUntilReload(300_000, loadedAgoMs);
+    seedReload({ ses_a: record }, loadedAgoMs);
+
+    // A turn starting this long after load is a new turn, not the one that was
+    // running before the reload.
+    const before = Date.now();
+    snapshot(['ses_a'], ['ses_a']);
+
+    expect(startedAt('ses_a')).toBeGreaterThanOrEqual(before);
+  });
+
+  // Regression: bootstrap fetches status and sessions in parallel, so a
+  // snapshot can legitimately cover a session before it can see it busy.
+  // Treating that as "the turn ended" used to destroy the persisted start
+  // moments before the real busy snapshot arrived, resetting the counter to 0s.
+  test('an early snapshot that cannot see the session busy does not lose the start', () => {
+    const record = runningUntilReload(120_000);
+    seedReload({ ses_a: record });
+
+    applyGlobalSessionStatusSnapshot('/repo', {}, ['ses_a']);
+    applyGlobalSessionStatusSnapshot('/repo', { ses_a: { type: 'busy' } }, ['ses_a']);
+
+    expect(startedAt('ses_a')).toBe(record.start);
+  });
+
+  test('resumes through a snapshot that arrives before the session list loads', () => {
+    const record = runningUntilReload(120_000);
+    seedReload({ ses_a: record });
+
+    applyGlobalSessionStatusSnapshot('/repo', { ses_a: { type: 'busy' } }, []);
+
+    expect(startedAt('ses_a')).toBe(record.start);
+  });
+
+  test('does not resume a record whose liveness stamp has gone quiet', () => {
+    const before = Date.now();
+    seedReload({ ses_a: { start: before - 300_000, seen: before - 240_000 } });
+
+    snapshot(['ses_a'], ['ses_a']);
+
+    expect(startedAt('ses_a')).toBeGreaterThanOrEqual(before);
+  });
+
+  test('does not resume a turn older than the maximum turn age', () => {
+    const before = Date.now();
+    seedReload({ ses_a: { start: before - 48 * 60 * 60 * 1000, seen: before - 1_000 } });
+
+    snapshot(['ses_a'], ['ses_a']);
+
+    expect(startedAt('ses_a')).toBeGreaterThanOrEqual(before);
+  });
+
+  test('ignores malformed persisted payloads', () => {
+    getSafeStorage().setItem(STORAGE_KEY, 'not json');
+    resetSessionActivityTiming();
+
+    const before = Date.now();
+    snapshot(['ses_a'], ['ses_a']);
+
+    expect(startedAt('ses_a')).toBeGreaterThanOrEqual(before);
+  });
+
+  test('ignores entries of the wrong shape or dated in the future', () => {
+    const before = Date.now();
+    seedReload({
+      ses_a: before - 5_000,
+      ses_b: { start: 'nope', seen: before },
+      ses_c: { start: before + 60_000, seen: before },
+      ses_d: { start: before - 5_000, seen: before + 60_000 },
+    });
+
+    for (const sessionId of ['ses_a', 'ses_b', 'ses_c', 'ses_d']) {
+      snapshot([sessionId]);
+      expect(startedAt(sessionId)).toBeGreaterThanOrEqual(before);
+    }
+  });
+
+  test('a quiet record ages out of storage on the next write', () => {
+    const before = Date.now();
+    seedReload({ ses_quiet: { start: before - 300_000, seen: before - 240_000 } });
+
+    observeSessionActivityTiming('ses_a', 'active');
+
+    expect(readPersisted()?.ses_quiet).toBe(undefined);
+    expect(readPersisted()?.ses_a.start).toBeDefined();
+  });
+
+  test('deleting a session clears live, settled, and persisted timing', () => {
+    observeSessionActivityTiming('ses_a', 'active');
+    observeSessionActivityTiming('ses_b', 'active');
+    observeSessionActivityTiming('ses_b', 'settled');
+
+    removeSessionActivityTiming('ses_a');
+    removeSessionActivityTiming('ses_b');
+
+    expect(startedAt('ses_a')).toBe(undefined);
+    expect(settledMs('ses_b')).toBe(undefined);
+    expect(readPersisted()).toBeNull();
+  });
+
+  test('unrelated sessions keep their map references across a no-op update', () => {
+    observeSessionActivityTiming('ses_a', 'active');
+    const before = useSessionActivityTimingStore.getState();
+
+    observeSessionActivityTiming('ses_a', 'active');
+    observeSessionActivityTiming('ses_unknown', 'settled');
+
+    const after = useSessionActivityTimingStore.getState();
+    expect(after.startedAt).toBe(before.startedAt);
+    expect(after.settledMs).toBe(before.settledMs);
+  });
+});
diff --git a/packages/ui/src/sync/session-activity-timing.ts b/packages/ui/src/sync/session-activity-timing.ts
new file mode 100644
index 00000000..288696c4
--- /dev/null
+++ b/packages/ui/src/sync/session-activity-timing.ts
@@ -0,0 +1,444 @@
+import { useCallback } from 'react';
+import { create } from 'zustand';
+import { getSafeStorage } from '@/stores/utils/safeStorage';
+
+// Per-session turn timing behind the sidebar activity readout.
+//
+// The OpenCode status contract carries no timestamps — `SessionStatus` is a
+// bare `busy | retry | idle` union — so how long the current turn has been
+// running has to be measured on the client. This module owns that measurement
+// and is driven from the same two write paths as `global-session-status`, the
+// index rows actually render their live state from, so a row can never count a
+// turn that index calls idle.
+//
+// Two maps with deliberately different lifetimes:
+//
+// - `startedAt` — sessions observed active right now. Persisted, so reloading
+//   the page resumes the same count instead of restarting it at zero.
+// - `settledMs` — how long the turn that just finished took. In memory only:
+//   rows show it while the session is unread, and unread state itself does not
+//   survive a reload, so persisting it would outlive its only consumer.
+//
+// A persisted start is a lookup table, never a claim of activity. Nothing in
+// the protocol marks where a turn begins: the server calls `SessionStatus.set`
+// with `busy` at every step of the agent loop and publishes an event each time,
+// so a busy event means "still running", not "just started" — it cannot be read
+// as a turn boundary, and reading it that way reset every counter on reload,
+// because after a refresh one of those repeats almost always beats the first
+// status snapshot.
+//
+// Turn *ends* are marked: `session.idle` and `session.error` events fire once,
+// live, and retire the persisted record.
+//
+// That leaves the case with no observable answer at all: a turn that ended, and
+// another that began, entirely while the tab was gone. Two bounds stand in for
+// the evidence the client cannot have:
+//
+// - a liveness stamp beside the start, refreshed while the session is observed
+//   active and stamped precisely as the page hides, compared against this page's
+//   navigation start — how long the app was actually absent;
+// - an adoption window after load, after which unclaimed records are discarded,
+//   which backstops a runtime whose event stream is down and where snapshots are
+//   therefore the only signal.
+//
+// Nothing else may drop a persisted start. Status snapshots legitimately arrive
+// before they can see a session as busy — bootstrap fetches status and sessions
+// in parallel, directory scopes resolve at different times — and treating one
+// of those as "the turn ended" destroyed the start moments before the real busy
+// snapshot arrived, which is exactly the reload-resets-to-zero bug. Absence of
+// evidence is not evidence here; only the two bounds above expire a record.
+
+type SessionActivityPhase = 'active' | 'settled';
+
+
+type SessionActivityTimingState = {
+  startedAt: ReadonlyMap<string, number>;
+  settledMs: ReadonlyMap<string, number>;
+};
+
+/** Persisted per session: when this turn began, and when it was last alive. */
+type PersistedStart = { start: number; seen: number };
+
+/** Finished turns worth remembering at once; each row only needs its own. */
+const SETTLED_LIMIT = 200;
+/** A turn running longer than this is treated as a stale record, not a turn. */
+const MAX_TURN_AGE_MS = 24 * 60 * 60 * 1000;
+/**
+ * How long the app may have been gone and still have its counters resumed,
+ * measured from the liveness stamp to this page's navigation start — not to
+ * "now". Bootstrap latency belongs to this page, not to the absence, and this
+ * client has seen 20-second startups; charging those to the gap would refuse
+ * a legitimate resume on exactly the slowest machines.
+ */
+const MAX_AWAY_MS = 30_000;
+/** Refresh the persisted stamp at most this often during a long turn. */
+const LIVENESS_PERSIST_INTERVAL_MS = 15_000;
+/**
+ * How long after page load a persisted record may still be adopted. Past this
+ * point the app has certainly seen live status, so a record nothing claimed
+ * describes a turn that is over — and a turn starting later is a new one that
+ * must count from zero.
+ */
+const RESTORE_ADOPTION_WINDOW_MS = 90_000;
+// One key, not one per runtime. These records live for seconds and are keyed by
+// instance-unique session IDs, so runtime scoping bought nothing while adding a
+// real failure mode: the runtime key is derived from injected globals and is not
+// guaranteed stable across early startup, and a read under a key the previous
+// page did not write to looks exactly like "no turn was running".
+const STORAGE_KEY = 'oc.session-activity.v1';
+
+const EMPTY_ACTIVE: ReadonlySet<string> = new Set();
+const EMPTY_RESTORED: ReadonlyMap<string, PersistedStart> = new Map();
+
+export const useSessionActivityTimingStore = create<SessionActivityTimingState>(() => ({
+  startedAt: new Map(),
+  settledMs: new Map(),
+}));
+
+/** Last moment each live start was observed active, for the liveness stamp. */
+const liveSeen = new Map<string, number>();
+let lastPersistAt = 0;
+
+// ---------------------------------------------------------------------------
+// Persistence
+// ---------------------------------------------------------------------------
+
+let restoredStarts: Map<string, PersistedStart> | null = null;
+
+/** Epoch ms of this page's navigation start; the reference for "how long gone". */
+const readPageLoadAt = (): number => {
+  if (typeof performance !== 'undefined' && Number.isFinite(performance.timeOrigin)) {
+    return performance.timeOrigin;
+  }
+  return Date.now();
+};
+
+let pageLoadAt = readPageLoadAt();
+
+const isResumable = (entry: PersistedStart, now: number): boolean => (
+  entry.start <= now
+  && now - entry.start <= MAX_TURN_AGE_MS
+  && entry.seen <= now
+  // Negative when this page wrote the stamp itself, which is trivially fresh.
+  && pageLoadAt - entry.seen <= MAX_AWAY_MS
+);
+
+const parseEntry = (value: unknown): PersistedStart | null => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const { start, seen } = value as { start?: unknown; seen?: unknown };
+  if (typeof start !== 'number' || !Number.isFinite(start)) return null;
+  if (typeof seen !== 'number' || !Number.isFinite(seen)) return null;
+  return { start, seen };
+};
+
+const readRestoredStarts = (): Map<string, PersistedStart> => {
+  const restored = new Map<string, PersistedStart>();
+  let raw: string | null = null;
+  try {
+    raw = getSafeStorage().getItem(STORAGE_KEY);
+  } catch {
+    return restored;
+  }
+  if (!raw) return restored;
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    // Malformed payload is a failed read, not authoritative "no turns were
+    // running": live status re-seeds every counter from now either way.
+    return restored;
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return restored;
+
+  const now = Date.now();
+  for (const [sessionId, value] of Object.entries(parsed as Record<string, unknown>)) {
+    const entry = parseEntry(value);
+    // Rejects stale turns, quiet stamps, and clock-skewed futures rather than
+    // rendering a counter that reads days long or negative.
+    if (entry && isResumable(entry, now)) restored.set(sessionId, entry);
+  }
+  return restored;
+};
+
+const getRestoredStarts = (): Map<string, PersistedStart> => {
+  restoredStarts ??= readRestoredStarts();
+  return restoredStarts;
+};
+
+/**
+ * Restored records still eligible to be adopted. Past the adoption window they
+ * are dropped for good, so a turn that starts later counts from zero instead of
+ * inheriting the start of whatever ran before the reload.
+ */
+const getAdoptableStarts = (now: number): ReadonlyMap<string, PersistedStart> => {
+  if (now - pageLoadAt > RESTORE_ADOPTION_WINDOW_MS) {
+    restoredStarts?.clear();
+    return EMPTY_RESTORED;
+  }
+  return getRestoredStarts();
+};
+
+// Live starts merged over restored-but-unconfirmed ones, so a reload landing
+// before the first authoritative snapshot does not drop the starts that
+// snapshot is about to confirm. Restored entries whose stamp has gone quiet are
+// dropped here, which is the only way they leave storage.
+const persistStarts = (startedAt: ReadonlyMap<string, number>, now: number): void => {
+  const payload: Record<string, PersistedStart> = {};
+  for (const [sessionId, entry] of getRestoredStarts()) {
+    if (isResumable(entry, now)) payload[sessionId] = entry;
+  }
+  for (const [sessionId, start] of startedAt) {
+    payload[sessionId] = { start, seen: liveSeen.get(sessionId) ?? now };
+  }
+
+  lastPersistAt = now;
+  try {
+    const storage = getSafeStorage();
+    if (Object.keys(payload).length === 0) {
+      storage.removeItem(STORAGE_KEY);
+      return;
+    }
+    storage.setItem(STORAGE_KEY, JSON.stringify(payload));
+  } catch {
+    // Storage is unavailable or full; counters simply restart after a reload.
+  }
+};
+
+// The most accurate liveness stamp available: the page is going away and every
+// running turn was still running as of now. Writes are immediate (not deferred)
+// so this cannot lose the race against a deferred flush on the same event.
+const stampLiveness = (): void => {
+  const { startedAt } = useSessionActivityTimingStore.getState();
+  if (startedAt.size === 0) return;
+  const now = Date.now();
+  for (const sessionId of startedAt.keys()) liveSeen.set(sessionId, now);
+  persistStarts(startedAt, now);
+};
+
+let lifecycleHooked = false;
+
+const ensureLivenessStampOnHide = (): void => {
+  if (lifecycleHooked || typeof window === 'undefined') return;
+  lifecycleHooked = true;
+  try {
+    // `pagehide` covers unload and bfcache entry; `visibilitychange`/`freeze`
+    // cover backgrounding and are the reliable ones in WKWebView. No
+    // `beforeunload` — it would cost bfcache for a stamp the others already
+    // wrote.
+    window.addEventListener('pagehide', stampLiveness, { capture: true });
+    if (typeof document !== 'undefined') {
+      document.addEventListener('visibilitychange', () => {
+        if (document.visibilityState === 'hidden') stampLiveness();
+      });
+      document.addEventListener('freeze', stampLiveness);
+    }
+  } catch {
+    // Restricted environments can reject listeners; the periodic stamp refresh
+    // still bounds how quiet a running turn's record can get.
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Transitions
+// ---------------------------------------------------------------------------
+
+const trimSettled = (settled: Map<string, number>): void => {
+  while (settled.size > SETTLED_LIMIT) {
+    const oldest = settled.keys().next();
+    if (oldest.done) return;
+    settled.delete(oldest.value);
+  }
+};
+
+/**
+ * What ends a turn in this pass. An event names its session outright; a snapshot
+ * only answers whether it covers a given one — deliberately the cheaper
+ * question, since the settle loop walks running turns rather than session lists.
+ * An `event` idle is a live, one-shot "this turn is over"; a snapshot omitting a
+ * session is not, because it may simply not see it yet.
+ */
+type SettleInput =
+  | { source: 'event'; sessionId: string }
+  | { source: 'snapshot'; isCovered: (sessionId: string) => boolean };
+
+const applyTransitions = (
+  activeSessionIds: ReadonlySet<string>,
+  settle: SettleInput | null,
+): void => {
+  const now = Date.now();
+  const restored = getAdoptableStarts(now);
+  const state = useSessionActivityTimingStore.getState();
+
+  const next: { started: Map<string, number> | null; settled: Map<string, number> | null } = {
+    started: null,
+    settled: null,
+  };
+  let sawActive = false;
+  let restoredChanged = false;
+
+  const draftStarted = (): Map<string, number> => (next.started ??= new Map(state.startedAt));
+  const draftSettled = (): Map<string, number> => (next.settled ??= new Map(state.settledMs));
+
+  for (const sessionId of activeSessionIds) {
+    sawActive = true;
+    liveSeen.set(sessionId, now);
+    if ((next.started ?? state.startedAt).has(sessionId)) continue;
+    // Busy carries no turn boundary from either source: the server re-publishes
+    // `session.status: busy` on every step of the agent loop, so a busy event
+    // means "still running", not "just started". Both paths therefore prefer a
+    // persisted start when one survives; only the bounds below expire it.
+    draftStarted().set(sessionId, restored.get(sessionId)?.start ?? now);
+    if ((next.settled ?? state.settledMs).has(sessionId)) draftSettled().delete(sessionId);
+  }
+
+  const settleTurn = (sessionId: string, start: number): void => {
+    draftStarted().delete(sessionId);
+    liveSeen.delete(sessionId);
+    draftSettled().set(sessionId, Math.max(0, now - start));
+  };
+
+  if (settle === null) {
+    // Nothing ends this pass.
+  } else if (settle.source === 'event') {
+    // An idle/error event is a live, unambiguous end of turn, so it also retires
+    // the persisted record. A snapshot's silence is not: it may simply not see
+    // the session yet.
+    if (getRestoredStarts().delete(settle.sessionId)) restoredChanged = true;
+    const start = state.startedAt.get(settle.sessionId);
+    // Only a turn watched from its start yields a duration.
+    if (start !== undefined) settleTurn(settle.sessionId, start);
+  } else {
+    // Walk the running turns, not everything the snapshot covers. Only a live
+    // start can settle, and there are a handful of those against a directory's
+    // hundreds of sessions — asking "does this snapshot cover that one?" keeps
+    // the pass proportional to the work instead of to the session list, and
+    // allocates nothing per poll.
+    for (const [sessionId, start] of state.startedAt) {
+      if (activeSessionIds.has(sessionId)) continue;
+      if (!settle.isCovered(sessionId)) continue;
+      settleTurn(sessionId, start);
+    }
+  }
+
+  if (next.settled) trimSettled(next.settled);
+
+  if (next.started || next.settled) {
+    useSessionActivityTimingStore.setState({
+      startedAt: next.started ?? state.startedAt,
+      settledMs: next.settled ?? state.settledMs,
+    });
+  }
+
+  if (next.started) {
+    if (next.started.size > 0) ensureLivenessStampOnHide();
+    persistStarts(next.started, now);
+    return;
+  }
+  if (restoredChanged) {
+    persistStarts(state.startedAt, now);
+    return;
+  }
+  // Nothing structural changed, but a long-running turn still needs its stamp
+  // refreshed so a reload can tell it apart from one that ended unobserved.
+  if (sawActive && state.startedAt.size > 0 && now - lastPersistAt >= LIVENESS_PERSIST_INTERVAL_MS) {
+    persistStarts(state.startedAt, now);
+  }
+};
+
+/**
+ * Event-driven path: one session changed phase, live. Busy repeats throughout a
+ * turn and carries no boundary; idle/error fire once and end it, which is why
+ * only settling here retires the persisted record.
+ */
+export const observeSessionActivityTiming = (
+  sessionId: string,
+  phase: SessionActivityPhase,
+): void => {
+  if (phase === 'active') {
+    applyTransitions(new Set([sessionId]), null);
+    return;
+  }
+  applyTransitions(EMPTY_ACTIVE, { source: 'event', sessionId });
+};
+
+/**
+ * Authoritative path: a `/session/status` snapshot for one directory. Sessions
+ * the snapshot covers but does not report active stop their live counters —
+ * that is what recovers a turn whose end event this client missed — but their
+ * persisted records survive, because a snapshot that cannot yet see a session
+ * looks identical to one whose turn is over.
+ */
+export const reconcileSessionActivityTiming = (
+  activeSessionIds: ReadonlySet<string>,
+  isCoveredBySnapshot: (sessionId: string) => boolean,
+): void => {
+  applyTransitions(activeSessionIds, { source: 'snapshot', isCovered: isCoveredBySnapshot });
+};
+
+export const removeSessionActivityTiming = (sessionId: string): void => {
+  const restoredChanged = getRestoredStarts().delete(sessionId);
+  const state = useSessionActivityTimingStore.getState();
+  const hadStart = state.startedAt.has(sessionId);
+  const hadSettled = state.settledMs.has(sessionId);
+  liveSeen.delete(sessionId);
+
+  if (!hadStart && !hadSettled) {
+    if (restoredChanged) persistStarts(state.startedAt, Date.now());
+    return;
+  }
+
+  let startedAt = state.startedAt;
+  if (hadStart) {
+    const draft = new Map(state.startedAt);
+    draft.delete(sessionId);
+    startedAt = draft;
+  }
+  let settledMs = state.settledMs;
+  if (hadSettled) {
+    const draft = new Map(state.settledMs);
+    draft.delete(sessionId);
+    settledMs = draft;
+  }
+
+  useSessionActivityTimingStore.setState({ startedAt, settledMs });
+  if (hadStart || restoredChanged) persistStarts(startedAt, Date.now());
+};
+
+/**
+ * Drops in-memory state and the cached restored-start snapshot — i.e. treats
+ * what follows as a fresh page load. Called on a runtime switch, where the
+ * previous instance's turns are no longer ours, and by tests. `pageLoadAt`
+ * overrides the navigation-start reference so tests can place a load in the
+ * past (slow bootstrap, expired window).
+ */
+export const resetSessionActivityTiming = (options: { pageLoadAt?: number } = {}): void => {
+  restoredStarts = null;
+  liveSeen.clear();
+  lastPersistAt = 0;
+  pageLoadAt = options.pageLoadAt ?? Date.now();
+  useSessionActivityTimingStore.setState({ startedAt: new Map(), settledMs: new Map() });
+};
+
+// ---------------------------------------------------------------------------
+// Leaf subscriptions
+// ---------------------------------------------------------------------------
+
+export const useSessionActivityStartedAt = (sessionId: string): number | undefined => (
+  useSessionActivityTimingStore(useCallback((state) => state.startedAt.get(sessionId), [sessionId]))
+);
+
+export const useSessionSettledDurationMs = (sessionId: string): number | undefined => (
+  useSessionActivityTimingStore(useCallback((state) => state.settledMs.get(sessionId), [sessionId]))
+);
+
+/**
+ * Whether a duration exists to render, without subscribing the caller to the
+ * value itself — a row uses this to decide between the counter and its normal
+ * metadata, and must not re-render every tick to do so.
+ */
+export const useHasSessionActivityDuration = (sessionId: string, running: boolean): boolean => (
+  useSessionActivityTimingStore(useCallback((state) => (
+    running ? state.startedAt.has(sessionId) : state.settledMs.has(sessionId)
+  ), [running, sessionId]))
+);

From 34c221b07fadd11e9ae7de43563fbc8531b644af Mon Sep 17 00:00:00 2001
From: Bohdan Triapitsyn <artmore@protonmail.com>
Date: Wed, 5 Aug 2026 03:10:29 +0300
Subject: [PATCH 16/57] fix(test): restore the issue-2039 suite by completing
 its session-actions mock
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The suite mocks `session-actions` by listing its exports one by one, and had
fallen behind `unarchiveSession`/`unarchiveSessions`. `session-ui-store` imports
both, so the file threw on import and ran zero tests — the draft auto-accept and
canonical-worktree-directory guarantees it covers were unprotected, and the
report looked almost like silence rather than a failure.
---
 packages/ui/src/sync/__tests__/issue-2039.test.ts | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/packages/ui/src/sync/__tests__/issue-2039.test.ts b/packages/ui/src/sync/__tests__/issue-2039.test.ts
index ef9f5439..c9cef4af 100644
--- a/packages/ui/src/sync/__tests__/issue-2039.test.ts
+++ b/packages/ui/src/sync/__tests__/issue-2039.test.ts
@@ -251,6 +251,8 @@ mock.module("../session-actions", () => ({
   deleteSessions: mock(async () => ({ deletedIds: [], failedIds: [] })),
   archiveSession: mock(async () => true),
   archiveSessions: mock(async () => ({ archivedIds: [], failedIds: [] })),
+  unarchiveSession: mock(async () => true),
+  unarchiveSessions: mock(async () => ({ restoredIds: [], failedIds: [] })),
   updateSessionTitle: mock(async () => undefined),
   shareSession: mock(async () => undefined),
   unshareSession: mock(async () => undefined),

From 41a2e3781d1e95620abb72497c0b9e41d1445157 Mon Sep 17 00:00:00 2001
From: Serhii Dziupin <serkraser@gmail.com>
Date: Wed, 5 Aug 2026 11:24:10 +0300
Subject: [PATCH 17/57] fix(cli): generate a UI password for bare --ui-password
 in daemon/serve mode

The grand tunnel restructuring removed the CLI's auto-generated UI
password, so `openchamber -d --ui-password` (no value) silently started
an unauthenticated server instead of creating a password as in 1.8.1.

Restore generation for an explicit --ui-password flag without a value:
the password is generated before either launch path, passed to the
daemon/foreground process via OPENCHAMBER_UI_PASSWORD, persisted in the
instance state file, and surfaced once in human/quiet/json output.

Refs OPE-216
---
 packages/web/bin/cli.js                |  4 +++
 packages/web/bin/cli.test.js           | 39 ++++++++++++++++++++++++++
 packages/web/bin/lib/cli-args.js       |  4 +--
 packages/web/bin/lib/cli-network.js    | 30 ++++++++++++++++++++
 packages/web/bin/lib/commands-serve.js | 38 +++++++++++++++++++++----
 5 files changed, 108 insertions(+), 7 deletions(-)

diff --git a/packages/web/bin/cli.js b/packages/web/bin/cli.js
index 36058032..098e9005 100755
--- a/packages/web/bin/cli.js
+++ b/packages/web/bin/cli.js
@@ -9,6 +9,8 @@ import { EXIT_CODE, TunnelCliError } from './lib/cli-errors.js';
 import {
   resolveServeHost,
   hasUiPasswordConfigured,
+  generateUiPassword,
+  resolveServeUiPassword,
   assertAuthenticatedNetworkExposure,
 } from './lib/cli-network.js';
 import {
@@ -428,6 +430,8 @@ export {
   assertAuthenticatedNetworkExposure,
   resolveServeHost,
   hasUiPasswordConfigured,
+  generateUiPassword,
+  resolveServeUiPassword,
   shouldDisplayTunnelQr,
   isValidTunnelDoctorResponse,
   readDesktopLocalPortFromSettings,
diff --git a/packages/web/bin/cli.test.js b/packages/web/bin/cli.test.js
index 7cc00660..5c2adbf4 100644
--- a/packages/web/bin/cli.test.js
+++ b/packages/web/bin/cli.test.js
@@ -34,12 +34,14 @@ import {
   discoverRunningInstances,
   discoverUnconfirmedRegistryInstanceOnPort,
   ensureTunnelProfilesMigrated,
+  generateUiPassword,
   getInstanceFilePath,
   getPidFilePath,
   isOpenchamberCmdline,
   isOpenchamberProcessRunning,
   parseArgs,
   resolveServeHost,
+  resolveServeUiPassword,
 } from './cli.js';
 
 async function withTempOpenChamberDataDir(fn) {
@@ -692,6 +694,43 @@ describe('network-exposed auth validation', () => {
   });
 });
 
+describe('serve UI password resolution', () => {
+  it('keeps a configured password untouched', () => {
+    expect(resolveServeUiPassword({ uiPassword: 'secret', explicitUiPassword: true }))
+      .toEqual({ password: 'secret', generated: false });
+  });
+
+  it('generates a password for an explicit --ui-password flag without a value', () => {
+    const resolved = resolveServeUiPassword({ uiPassword: '', explicitUiPassword: true });
+    expect(resolved.generated).toBe(true);
+    expect(typeof resolved.password).toBe('string');
+    expect(resolved.password.length).toBe(16);
+  });
+
+  it('does not generate a password when the flag is absent', () => {
+    expect(resolveServeUiPassword({ uiPassword: undefined, explicitUiPassword: false }))
+      .toEqual({ password: undefined, generated: false });
+  });
+
+  it('generates passwords from an ambiguity-free charset', () => {
+    const resolved = resolveServeUiPassword({ uiPassword: '', explicitUiPassword: true });
+    expect(resolved.password).toMatch(/^[A-HJ-NP-Za-km-z2-9]{16}$/);
+    expect(resolved.password).not.toMatch(/[0O1Il]/);
+  });
+
+  it('generates distinct passwords on repeated calls', () => {
+    const a = generateUiPassword();
+    const b = generateUiPassword();
+    expect(a).not.toBe(b);
+  });
+
+  it('parses --ui-password without a value as explicit but empty', () => {
+    const parsed = parseArgs(['serve', '--ui-password']);
+    expect(parsed.options.explicitUiPassword).toBe(true);
+    expect(parsed.options.uiPassword).toBe('');
+  });
+});
+
 describe('serve host resolution', () => {
   it('uses OPENCHAMBER_HOST when --host is not provided', () => {
     const previous = process.env.OPENCHAMBER_HOST;
diff --git a/packages/web/bin/lib/cli-args.js b/packages/web/bin/lib/cli-args.js
index deeccb94..1bc9c387 100644
--- a/packages/web/bin/lib/cli-args.js
+++ b/packages/web/bin/lib/cli-args.js
@@ -593,7 +593,7 @@ OPTIONS:
   --lan                   Bind to 0.0.0.0 for LAN access
   --server <url>          Public/server URL for connect-url links
   --relay                 connect-url: also include the end-to-end-encrypted relay transport
-  --ui-password           Protect browser UI with single password
+  --ui-password [password] Protect browser UI with a password (generates one when omitted)
   --api-only              Start API routes only, without serving browser UI assets
   --foreground            Run server in foreground (use with systemd/process managers)
   --no-daemon             Alias for --foreground
@@ -752,7 +752,7 @@ COMMON OPTIONS:
   -p, --port              Target OpenChamber instance port
   --host                  Bind address when auto-starting an instance
   --lan                   Bind to 0.0.0.0 when auto-starting an instance
-  --ui-password           Protect browser UI when auto-starting an instance
+  --ui-password [password] Protect browser UI when auto-starting an instance (generates one when omitted)
   --api-only              Start API routes only when auto-starting an instance
   --json                  Output machine-readable JSON
   --all                   Apply to all running instances (doctor default, stop)
diff --git a/packages/web/bin/lib/cli-network.js b/packages/web/bin/lib/cli-network.js
index 7e0e666a..992a9e94 100644
--- a/packages/web/bin/lib/cli-network.js
+++ b/packages/web/bin/lib/cli-network.js
@@ -1,5 +1,6 @@
 import dgram from 'dgram';
 import os from 'os';
+import { randomInt } from 'node:crypto';
 import { EXIT_CODE, TunnelCliError } from './cli-errors.js';
 import {
   getUnauthenticatedLanErrorMessage,
@@ -125,6 +126,33 @@ function hasUiPasswordConfigured(password) {
   return typeof password === 'string' && password.trim().length > 0;
 }
 
+// Ambiguous-character-free alphabet so the printed password is easy to type
+// from a phone or another machine. Mirrors the pre-refactor CLI alphabet.
+const UI_PASSWORD_CHARSET = 'ABCDEFGHJKLMNPQRSTUVWXYZabcdefghjkmnpqrstuvwxyz23456789';
+
+function generateUiPassword(length = 16) {
+  let password = '';
+  for (let i = 0; i < length; i++) {
+    password += UI_PASSWORD_CHARSET[randomInt(UI_PASSWORD_CHARSET.length)];
+  }
+  return password;
+}
+
+// Resolves the effective UI password for a serve: a configured password wins;
+// an explicit `--ui-password` flag without a value gets a freshly generated
+// password so daemon/foreground serves never silently drop the requested
+// protection. The caller must surface `generated` passwords to the user once
+// and persist them in the instance state file the server-side reads.
+function resolveServeUiPassword({ uiPassword, explicitUiPassword }) {
+  if (hasUiPasswordConfigured(uiPassword)) {
+    return { password: uiPassword, generated: false };
+  }
+  if (explicitUiPassword === true) {
+    return { password: generateUiPassword(), generated: true };
+  }
+  return { password: undefined, generated: false };
+}
+
 function assertAuthenticatedNetworkExposure({ host, uiPassword }) {
   const bindHost = resolveConfiguredBindHost(host);
   if (hasUiPasswordConfigured(uiPassword)) {
@@ -150,5 +178,7 @@ export {
   detectLanIPv4Address,
   assertSafeBrowserPort,
   hasUiPasswordConfigured,
+  generateUiPassword,
+  resolveServeUiPassword,
   assertAuthenticatedNetworkExposure,
 };
diff --git a/packages/web/bin/lib/commands-serve.js b/packages/web/bin/lib/commands-serve.js
index 1475018a..48e0a6bc 100644
--- a/packages/web/bin/lib/commands-serve.js
+++ b/packages/web/bin/lib/commands-serve.js
@@ -2,7 +2,7 @@ import fs from 'fs';
 import { pathToFileURL } from 'url';
 import { spawn } from 'child_process';
 import { EXIT_CODE, TunnelCliError } from './cli-errors.js';
-import { buildLocalUrl, resolveServeHost, assertSafeBrowserPort, hasUiPasswordConfigured, assertAuthenticatedNetworkExposure } from './cli-network.js';
+import { buildLocalUrl, resolveServeHost, assertSafeBrowserPort, resolveServeUiPassword, assertAuthenticatedNetworkExposure } from './cli-network.js';
 import { fetchSystemInfoFromPort } from './cli-http.js';
 import { isPortAvailable, resolveAvailablePort } from './cli-ports.js';
 import { ensureLogsDir, getLogFilePath } from './cli-paths.js';
@@ -110,7 +110,13 @@ async function serveCommand(options) {
     rotateLogFile(initialLogPath);
     const logFd = fs.openSync(initialLogPath, 'a');
 
-    const effectiveUiPassword = hasUiPasswordConfigured(options.uiPassword) ? options.uiPassword : undefined;
+    // Resolve the effective UI password before either launch path so a
+    // password generated for `--ui-password` (no value) is set in the
+    // daemon/foreground environment before spawning and persisted in the
+    // instance state file the server and restart/status flows read.
+    const resolvedUiPassword = resolveServeUiPassword(options);
+    const effectiveUiPassword = resolvedUiPassword.password;
+    const autoGeneratedUiPassword = resolvedUiPassword.generated === true;
     assertAuthenticatedNetworkExposure({
       host: effectiveHost,
       uiPassword: effectiveUiPassword,
@@ -214,8 +220,15 @@ async function serveCommand(options) {
 
       if (isQuietMode(options)) {
         if (!options.suppressQuietOutput) {
-          realStdoutWrite(`${resolvedPort}\n`);
+          realStdoutWrite(
+            autoGeneratedUiPassword
+              ? `${resolvedPort} pass:${effectiveUiPassword}\n`
+              : `${resolvedPort}\n`
+          );
         }
+      } else if (autoGeneratedUiPassword && showOutput && !options.suppressStartupSummary) {
+        console.log(`Generated UI password: ${effectiveUiPassword}`);
+        console.log('Save this password — it is not shown again.');
       }
 
       // Clean up PID / instance files.
@@ -365,7 +378,11 @@ async function serveCommand(options) {
     };
 
     if (isJsonMode(options)) {
-      printJson({ ...serveResult, messages: jsonMessages });
+      printJson({
+        ...serveResult,
+        messages: jsonMessages,
+        ...(autoGeneratedUiPassword ? { password: effectiveUiPassword } : {}),
+      });
       return resolvedPort;
     }
 
@@ -373,7 +390,14 @@ async function serveCommand(options) {
       if (options.suppressQuietOutput) {
         return resolvedPort;
       }
-      process.stdout.write(`${resolvedPort}\n`);
+      // A generated password is essential result data for scripts: include it
+      // in the same compact `pass:` token form `openchamber status --quiet`
+      // already emits. Configured passwords are never echoed.
+      process.stdout.write(
+        autoGeneratedUiPassword
+          ? `${resolvedPort} pass:${effectiveUiPassword}\n`
+          : `${resolvedPort}\n`
+      );
       return resolvedPort;
     }
 
@@ -382,6 +406,10 @@ async function serveCommand(options) {
     if (!options.suppressStartupSummary && showOutput) {
       clackIntro('OpenChamber Started');
       logStatus('success', `port ${serveResult.port} (PID: ${serveResult.pid})`);
+      if (autoGeneratedUiPassword) {
+        logStatus('success', 'UI password', effectiveUiPassword);
+        logStatus('warning', 'save this password', 'it is not shown again');
+      }
       logStatus('info', `visit: ${serveResult.url}`);
       logStatus('info', `logs: ${serveResult.logs}`);
       clackOutro('daemon running');

From ddae6f2545272a957329a4463d039539b59338db Mon Sep 17 00:00:00 2001
From: Serhii Dziupin <serkraser@gmail.com>
Date: Wed, 5 Aug 2026 11:24:14 +0300
Subject: [PATCH 18/57] feat(server): validate OPENCHAMBER_OPENCODE_HOSTNAME
 bind hostname

The env var was already read and passed to the managed OpenCode server
spawn, but any non-empty string was accepted. Reject values that are
not a valid IP (IPv4/IPv6, brackets allowed) or DNS-style hostname with
a clear [config] error and fall back to the secure loopback default so
a typo can never silently bind a non-loopback address.

Refs OPE-231
---
 packages/web/README.md                        |  2 +-
 .../web/server/lib/opencode/env-config.js     | 31 ++++++
 .../server/lib/opencode/env-config.test.js    | 97 +++++++++++++++++++
 .../web/server/lib/opencode/lifecycle.test.js | 24 ++++-
 4 files changed, 152 insertions(+), 2 deletions(-)
 create mode 100644 packages/web/server/lib/opencode/env-config.test.js

diff --git a/packages/web/README.md b/packages/web/README.md
index 784b9a81..03e9e752 100644
--- a/packages/web/README.md
+++ b/packages/web/README.md
@@ -110,7 +110,7 @@ OPENCODE_HOST=https://myhost:4096 OPENCODE_SKIP_START=true openchamber
 | `OPENCODE_HOST` | Full base URL of external server (overrides `OPENCODE_PORT`) |
 | `OPENCODE_PORT` | Port of external server |
 | `OPENCODE_SKIP_START` | Skip starting embedded OpenCode server |
-| `OPENCHAMBER_OPENCODE_HOSTNAME` | Bind hostname for managed OpenCode server (default: `127.0.0.1`, use `0.0.0.0` for LAN/remote access — trusted networks only) |
+| `OPENCHAMBER_OPENCODE_HOSTNAME` | Bind hostname for managed OpenCode server (default: `127.0.0.1`, use `0.0.0.0` for LAN/remote access — trusted networks only). Invalid values are rejected with an error and fall back to loopback |
 | `OPENCHAMBER_HOST` | Bind hostname for the OpenChamber web server (default: `127.0.0.1`; use `0.0.0.0` for LAN/remote access — trusted networks only) |
 | `OPENCHAMBER_VERBOSE_REQUEST_LOGS` | Set to `true` to log every HTTP request; disabled by default to keep user logs small |
 | `OPENCHAMBER_SKIP_API_COMPRESSION` | Set to `true` to disable gzip compression for `/api/*` responses |
diff --git a/packages/web/server/lib/opencode/env-config.js b/packages/web/server/lib/opencode/env-config.js
index fc493f0b..42abd0a2 100644
--- a/packages/web/server/lib/opencode/env-config.js
+++ b/packages/web/server/lib/opencode/env-config.js
@@ -1,3 +1,26 @@
+import { isIP } from 'node:net';
+
+const MAX_HOSTNAME_LENGTH = 253;
+const HOSTNAME_LABEL_RE = /^[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?$/;
+// All-numeric dotted values must be a real IPv4 address; otherwise typo'd IPs
+// like "0.0.0.0.0" would slip through as (technically valid) hostnames.
+const ALL_NUMERIC_DOTTED_RE = /^\d+(?:\.\d+)*$/;
+
+// Valid bind hostnames for the managed OpenCode server: IPv4, IPv6 (with or
+// without brackets), or a DNS-style hostname. Everything else (URLs, ports,
+// paths, whitespace, underscores) is rejected.
+export const isValidOpenCodeHostname = (value) => {
+  if (typeof value !== 'string') return false;
+  const trimmed = value.trim();
+  if (!trimmed || trimmed.length > MAX_HOSTNAME_LENGTH) return false;
+  if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+    return isIP(trimmed.slice(1, -1)) === 6;
+  }
+  if (isIP(trimmed) !== 0) return true;
+  if (ALL_NUMERIC_DOTTED_RE.test(trimmed)) return false;
+  return trimmed.split('.').every((label) => HOSTNAME_LABEL_RE.test(label));
+};
+
 export const resolveOpenCodeEnvConfig = (options = {}) => {
   const env = options.env && typeof options.env === 'object' ? options.env : {};
   const logger = options.logger ?? console;
@@ -60,6 +83,14 @@ export const resolveOpenCodeEnvConfig = (options = {}) => {
       );
       return '127.0.0.1';
     }
+    if (!isValidOpenCodeHostname(trimmed)) {
+      logger.error(
+        `[config] Rejecting OPENCHAMBER_OPENCODE_HOSTNAME=${JSON.stringify(raw)}: `
+        + 'must be a valid hostname or IP address (for example 127.0.0.1, 0.0.0.0, localhost, [::1]); '
+        + 'falling back to 127.0.0.1 (loopback only)',
+      );
+      return '127.0.0.1';
+    }
     return trimmed;
   })();
 
diff --git a/packages/web/server/lib/opencode/env-config.test.js b/packages/web/server/lib/opencode/env-config.test.js
new file mode 100644
index 00000000..4b5f8bb0
--- /dev/null
+++ b/packages/web/server/lib/opencode/env-config.test.js
@@ -0,0 +1,97 @@
+import { describe, expect, it, vi } from 'vitest';
+import { isValidOpenCodeHostname, resolveOpenCodeEnvConfig } from './env-config.js';
+
+describe('isValidOpenCodeHostname', () => {
+  it('accepts IPv4 addresses', () => {
+    expect(isValidOpenCodeHostname('127.0.0.1')).toBe(true);
+    expect(isValidOpenCodeHostname('0.0.0.0')).toBe(true);
+    expect(isValidOpenCodeHostname('192.168.1.10')).toBe(true);
+  });
+
+  it('accepts IPv6 addresses with and without brackets', () => {
+    expect(isValidOpenCodeHostname('::1')).toBe(true);
+    expect(isValidOpenCodeHostname('[::1]')).toBe(true);
+    expect(isValidOpenCodeHostname('::')).toBe(true);
+    expect(isValidOpenCodeHostname('[::]')).toBe(true);
+  });
+
+  it('accepts DNS-style hostnames', () => {
+    expect(isValidOpenCodeHostname('localhost')).toBe(true);
+    expect(isValidOpenCodeHostname('tailscale-host')).toBe(true);
+    expect(isValidOpenCodeHostname('my.host.example')).toBe(true);
+  });
+
+  it('rejects malformed values', () => {
+    const invalid = [
+      '',
+      '   ',
+      'http://localhost',
+      'https://host:4096',
+      'host:4096',
+      'host/path',
+      'bad host',
+      'bad_host',
+      '0.0.0.0.0',
+      '999.999.999.999',
+      '[::1',
+      '::1]',
+      'a'.repeat(254),
+      '1.2.3.4.5.6.7.8.9',
+    ];
+    for (const value of invalid) {
+      expect(isValidOpenCodeHostname(value), JSON.stringify(value)).toBe(false);
+    }
+  });
+
+  it('rejects non-string values', () => {
+    expect(isValidOpenCodeHostname(undefined)).toBe(false);
+    expect(isValidOpenCodeHostname(null)).toBe(false);
+    expect(isValidOpenCodeHostname(42)).toBe(false);
+  });
+});
+
+describe('resolveOpenCodeEnvConfig hostname', () => {
+  it('defaults to loopback when the env var is absent', () => {
+    expect(resolveOpenCodeEnvConfig({ env: {} }).configuredOpenCodeHostname).toBe('127.0.0.1');
+  });
+
+  it('reads OPENCHAMBER_OPENCODE_HOSTNAME', () => {
+    const result = resolveOpenCodeEnvConfig({ env: { OPENCHAMBER_OPENCODE_HOSTNAME: '0.0.0.0' } });
+    expect(result.configuredOpenCodeHostname).toBe('0.0.0.0');
+  });
+
+  it('trims surrounding whitespace', () => {
+    const result = resolveOpenCodeEnvConfig({ env: { OPENCHAMBER_OPENCODE_HOSTNAME: '  tailscale-host  ' } });
+    expect(result.configuredOpenCodeHostname).toBe('tailscale-host');
+  });
+
+  it('warns and falls back for an empty value', () => {
+    const logger = { warn: vi.fn(), error: vi.fn() };
+    const result = resolveOpenCodeEnvConfig({ env: { OPENCHAMBER_OPENCODE_HOSTNAME: '   ' }, logger });
+    expect(result.configuredOpenCodeHostname).toBe('127.0.0.1');
+    expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining('empty after trimming'));
+    expect(logger.error).not.toHaveBeenCalled();
+  });
+
+  it('rejects invalid values with a clear error and falls back to loopback', () => {
+    const logger = { warn: vi.fn(), error: vi.fn() };
+    const result = resolveOpenCodeEnvConfig({
+      env: { OPENCHAMBER_OPENCODE_HOSTNAME: 'http://nope:4096' },
+      logger,
+    });
+    expect(result.configuredOpenCodeHostname).toBe('127.0.0.1');
+    expect(logger.error).toHaveBeenCalledWith(
+      expect.stringContaining('Rejecting OPENCHAMBER_OPENCODE_HOSTNAME'),
+    );
+    expect(logger.error).toHaveBeenCalledWith(expect.stringContaining('127.0.0.1'));
+  });
+
+  it('keeps other env config intact when the hostname is validated', () => {
+    const result = resolveOpenCodeEnvConfig({
+      env: { OPENCHAMBER_OPENCODE_HOSTNAME: '0.0.0.0', OPENCODE_PORT: '4096' },
+    });
+    expect(result.configuredOpenCodeHostname).toBe('0.0.0.0');
+    expect(result.configuredOpenCodePort).toBe(4096);
+    expect(result.effectivePort).toBe(4096);
+  });
+});
diff --git a/packages/web/server/lib/opencode/lifecycle.test.js b/packages/web/server/lib/opencode/lifecycle.test.js
index fb57c3f2..ee820972 100644
--- a/packages/web/server/lib/opencode/lifecycle.test.js
+++ b/packages/web/server/lib/opencode/lifecycle.test.js
@@ -50,7 +50,7 @@ const createMockChild = () => {
   return child;
 };
 
-const createRuntime = (overrides = {}, stateOverrides = {}) => {
+const createRuntime = (overrides = {}, stateOverrides = {}, envOverrides = {}) => {
   const state = {
     openCodeWorkingDirectory: '/tmp/project',
     openCodeProcess: null,
@@ -83,6 +83,7 @@ const createRuntime = (overrides = {}, stateOverrides = {}) => {
       ENV_EFFECTIVE_PORT: 3001,
       ENV_CONFIGURED_OPENCODE_HOSTNAME: '127.0.0.1',
       ENV_SKIP_OPENCODE_START: false,
+      ...envOverrides,
     },
     syncToHmrState: vi.fn(),
     syncFromHmrState: vi.fn(),
@@ -312,6 +313,27 @@ describe('OpenCode lifecycle', () => {
     expect(server.signalCode).toBe('SIGTERM');
   });
 
+  it('launches managed OpenCode on the configured bind hostname', async () => {
+    delete process.env.OPENCODE_BINARY;
+    const child = createMockChild();
+    spawnMock.mockImplementationOnce(() => {
+      queueMicrotask(() => {
+        child.stdout.emit('data', 'opencode server listening on http://0.0.0.0:45678\n');
+      });
+      return child;
+    });
+
+    const runtime = createRuntime({}, {}, { ENV_CONFIGURED_OPENCODE_HOSTNAME: '0.0.0.0' });
+    const server = await runtime.startOpenCode();
+    const [binary, args] = spawnMock.mock.calls[0];
+
+    expect(binary).toBe('opencode');
+    expect(args).toEqual(['serve', '--hostname', '0.0.0.0', '--port', '45678']);
+
+    await server.close();
+    expect(server.signalCode).toBe('SIGTERM');
+  });
+
   it('strips AppImage ARGV0 from managed OpenCode launch env', async () => {
     delete process.env.OPENCODE_BINARY;
     const previousArgv0 = process.env.ARGV0;

From 0116739111422b8201162ab037fc9d7bf1f53ff8 Mon Sep 17 00:00:00 2001
From: Serhii Dziupin <serkraser@gmail.com>
Date: Wed, 5 Aug 2026 11:41:40 +0300
Subject: [PATCH 19/57] fix(sync): route question/permission replies by the
 request's own session directory

Answering a question tool (or a permission prompt) could leave the session
permanently stuck on "asking question": resolveDirectoryForBlockingRequest
returned the containing child-store key, which only proves containment.
For a worktree session (or any session whose record is grouped under a
parent project store), the reply was addressed to the parent directory's
OpenCode instance, where the pending request does not exist - the server
answered QuestionNotFoundError, the local request was removed, and the
trailing question-tool part stayed running with no recovery until Stop.

Resolve the directory from the request's own session record (server-
confirmed ownership: session.directory, then project.worktree) before
falling back to the containing store key. When a reply/reject comes back
not-found, also enqueue the settled-running-tool tail materialization so
the tool part converges to the server's actual state instead of leaving
the UI stuck.

Refs OPE-236
---
 packages/ui/src/sync/DOCUMENTATION.md        |   4 +
 packages/ui/src/sync/session-actions.test.ts | 159 +++++++++++++++++++
 packages/ui/src/sync/session-actions.ts      |  91 ++++++++++-
 packages/ui/src/sync/sync-context.tsx        |   6 +
 4 files changed, 256 insertions(+), 4 deletions(-)

diff --git a/packages/ui/src/sync/DOCUMENTATION.md b/packages/ui/src/sync/DOCUMENTATION.md
index 5699fc93..55b0afb9 100644
--- a/packages/ui/src/sync/DOCUMENTATION.md
+++ b/packages/ui/src/sync/DOCUMENTATION.md
@@ -255,6 +255,10 @@ Examples of global-store updates performed in `session-actions.ts`:
 - `deleteSession()` / `deleteSessions()` -> wait for server confirmation or `404`, then remove the session and its persisted state
 - `moveSessionToDirectory()` -> move the session between directory stores and update the global directory index
 
+### Blocking-request (question/permission) reply routing
+
+`respondToQuestion`, `rejectQuestion`, `respondToPermission`, and `dismissPermission` route the reply through `resolveDirectoryForBlockingRequest`. The directory chosen decides which OpenCode instance resolves the pending request, so it must be the **session record's own server-confirmed directory** (ownership), never the containing child-store key (containment): a project store legitimately holds its worktree sessions, and a reply addressed to the parent instance makes the server answer `QuestionNotFoundError` while the question stays pending in the worktree instance — the session is then stuck on the running question tool with no recovery. When a reply/reject comes back not-found, the stale request is removed locally and a `settled-running-tool` tail materialization is enqueued so the trailing tool part converges to the server's actual state instead of leaving the UI on "asking question" forever.
+
 ### Restore (unarchive) contract
 
 The OpenCode server cannot clear `time.archived` over HTTP: `session.update`
diff --git a/packages/ui/src/sync/session-actions.test.ts b/packages/ui/src/sync/session-actions.test.ts
index 84c276f8..d815b6dd 100644
--- a/packages/ui/src/sync/session-actions.test.ts
+++ b/packages/ui/src/sync/session-actions.test.ts
@@ -1461,6 +1461,165 @@ describe("rejectQuestion passes directory", () => {
   })
 })
 
+describe("blocking request reply routing and stale recovery (issue OPE-236)", () => {
+  const materializationCalls: Array<{ directory: string; sessionID: string; messageID: string }> = []
+  const enqueueMaterialization = (directory: string, sessionID: string, messageID: string) => {
+    materializationCalls.push({ directory, sessionID, messageID })
+  }
+
+  beforeEach(() => {
+    replyCalls.length = 0
+    scopedClientDirectories.length = 0
+    questionReplyError = null
+    questionRejectError = null
+    materializationCalls.length = 0
+  })
+
+  test("routes the question reply by the request's own session directory, not the containing store key", async () => {
+    // The question was asked by a worktree session whose record lives in the
+    // parent store (containment). The reply must be addressed to the session's
+    // own server-confirmed directory — otherwise the server resolves the
+    // parent instance, does not find the pending question, and answers
+    // QuestionNotFoundError, leaving the session stuck on "asking question".
+    const question = buildQuestion("q-wt", "session-wt")
+    const store = createStore({}, {
+      session: [{ id: "session-wt", directory: "/test/project/wt" } as Session],
+      question: { "session-wt": [question] },
+    })
+    const childStores = createChildStores([["/test/project", store]])
+
+    const { setActionRefs, respondToQuestion } = await import("./session-actions")
+    setActionRefs(mockSdk as unknown as OpencodeClient, childStores, () => "/test/project", enqueueMaterialization)
+
+    await respondToQuestion("session-wt", "q-wt", [["Yes"]])
+
+    expect(scopedClientDirectories).toEqual(["/test/project/wt"])
+    expect(replyCalls[0]?.params.directory).toBe("/test/project/wt")
+    expect(replyCalls[0]?.params.requestID).toBe("q-wt")
+  })
+
+  test("routes permission replies by the request's own session directory", async () => {
+    const permission = buildPermission("perm-wt", "session-wt")
+    const store = createStore(
+      { "session-wt": [permission] },
+      {
+        session: [{ id: "session-wt", directory: "/test/project/wt" } as Session],
+      },
+    )
+    const childStores = createChildStores([["/test/project", store]])
+
+    const { setActionRefs, respondToPermission } = await import("./session-actions")
+    setActionRefs(mockSdk as unknown as OpencodeClient, childStores, () => "/test/project", enqueueMaterialization)
+
+    await respondToPermission("session-wt", "perm-wt", "once")
+
+    expect(scopedClientDirectories).toEqual(["/test/project/wt"])
+    expect(replyCalls[0]?.params.directory).toBe("/test/project/wt")
+    expect(replyCalls[0]?.params.requestID).toBe("perm-wt")
+  })
+
+  test("falls back to the containing store key when the session record carries no directory", async () => {
+    const question = buildQuestion("q-1", "session-a")
+    const store = createStore({}, {
+      session: [{ id: "session-a" } as Session],
+      question: { "session-a": [question] },
+    })
+    const childStores = createChildStores([["/test/project", store]])
+
+    const { setActionRefs, respondToQuestion } = await import("./session-actions")
+    setActionRefs(mockSdk as unknown as OpencodeClient, childStores, () => "/test/project", enqueueMaterialization)
+
+    await respondToQuestion("session-a", "q-1", [["Yes"]])
+
+    expect(scopedClientDirectories).toEqual(["/test/project"])
+    expect(replyCalls[0]?.params.directory).toBe("/test/project")
+  })
+
+  test("enqueues settled-running-tool tail recovery when the question reply is not found", async () => {
+    const question = buildQuestion("q-stale", "session-a")
+    const store = createStore({}, {
+      session: [{ id: "session-a" } as Session],
+      question: { "session-a": [question] },
+      message: {
+        "session-a": [{ id: "msg-1", sessionID: "session-a", role: "assistant", time: { created: 1 } } as Message],
+      },
+      part: {
+        "msg-1": [{
+          id: "prt-1",
+          messageID: "msg-1",
+          sessionID: "session-a",
+          type: "tool",
+          tool: "question",
+          state: { status: "running" },
+        } as Part],
+      },
+    })
+    const childStores = createChildStores([["/test/project", store]])
+    questionReplyError = Object.assign(new Error("question.reply failed (404): QuestionNotFoundError"), { status: 404 })
+
+    const { setActionRefs, respondToQuestion } = await import("./session-actions")
+    setActionRefs(mockSdk as unknown as OpencodeClient, childStores, () => "/test/project", enqueueMaterialization)
+
+    let thrown: unknown
+    try {
+      await respondToQuestion("session-a", "q-stale", [["Yes"]])
+    } catch (error) {
+      thrown = error
+    }
+
+    expect(thrown).toBeInstanceOf(Error)
+    // The stale request is gone from the store and the trailing running tool
+    // part is reconciled instead of leaving the UI stuck on "asking question".
+    expect(store.getState().question["session-a"]).toBe(undefined)
+    expect(materializationCalls).toEqual([{ directory: "/test/project", sessionID: "session-a", messageID: "msg-1" }])
+  })
+
+  test("enqueues tail recovery on reject not-found but not on success", async () => {
+    const question = buildQuestion("q-1", "session-a")
+    const store = createStore({}, {
+      session: [{ id: "session-a" } as Session],
+      question: { "session-a": [question] },
+      message: {
+        "session-a": [{ id: "msg-1", sessionID: "session-a", role: "assistant", time: { created: 1 } } as Message],
+      },
+      part: {
+        "msg-1": [{
+          id: "prt-1",
+          messageID: "msg-1",
+          sessionID: "session-a",
+          type: "tool",
+          tool: "question",
+          state: { status: "running" },
+        } as Part],
+      },
+    })
+    const childStores = createChildStores([["/test/project", store]])
+
+    const { setActionRefs, rejectQuestion } = await import("./session-actions")
+    setActionRefs(mockSdk as unknown as OpencodeClient, childStores, () => "/test/project", enqueueMaterialization)
+
+    // Success: no recovery enqueued — the normal question.rejected event flow clears state.
+    await rejectQuestion("session-a", "q-1")
+    expect(materializationCalls).toEqual([])
+
+    // Not-found: the request is stale server-side; the tail must be reconciled.
+    questionRejectError = Object.assign(new Error("question.reject failed (404): QuestionNotFoundError"), { status: 404 })
+    const stale = buildQuestion("q-stale", "session-a")
+    store.setState({ question: { "session-a": [stale] } })
+
+    let thrown: unknown
+    try {
+      await rejectQuestion("session-a", "q-stale")
+    } catch (error) {
+      thrown = error
+    }
+
+    expect(thrown).toBeInstanceOf(Error)
+    expect(store.getState().question["session-a"]).toBe(undefined)
+    expect(materializationCalls).toEqual([{ directory: "/test/project", sessionID: "session-a", messageID: "msg-1" }])
+  })
+})
+
 function buildQuestion(id: string, sessionId: string): QuestionRequest {
   return {
     id,
diff --git a/packages/ui/src/sync/session-actions.ts b/packages/ui/src/sync/session-actions.ts
index 1b695891..aa8cdb10 100644
--- a/packages/ui/src/sync/session-actions.ts
+++ b/packages/ui/src/sync/session-actions.ts
@@ -30,6 +30,8 @@ import { getImperativeSessionMessageLoader } from "./session-message-loader"
 import { cleanupPersistedSessionState } from "./session-deletion-cleanup"
 import { getRuntimeKey } from "@/lib/runtime-switch"
 import { isAmbiguousTransportFailure } from "@/lib/relay/transport-error"
+import { getStaleRunningToolMessageID } from "./materialization"
+import { normalizePath } from "@/lib/pathNormalization"
 
 const MESSAGE_REFETCH_LIMIT = 100
 const SEND_CONFIRMATION_REFETCH_LIMIT = 30
@@ -52,6 +54,10 @@ const UNREVERT_REFETCH_RETRY_MS = 150
 let _sdk: OpencodeClient | null = null
 let _childStores: ChildStoreManager | null = null
 let _getDirectory: () => string = () => ""
+// Optional ref into the sync layer's session-tail materialization queue. Used
+// to reconcile a trailing running tool part after a blocking request is
+// confirmed stale server-side (see recoverStaleBlockingRequest).
+let _enqueueSessionMaterialization: ((directory: string, sessionID: string, messageID: string) => void) | null = null
 type OptimisticAddInput = { sessionID: string; directory?: string | null; message: Message; parts: Part[] }
 type OptimisticRemoveInput = { sessionID: string; directory?: string | null; messageID: string }
 type OptimisticConfirmInput = OptimisticRemoveInput
@@ -139,10 +145,12 @@ export function setActionRefs(
   sdk: OpencodeClient,
   childStores: ChildStoreManager,
   getDirectory: () => string,
+  enqueueSessionMaterialization?: (directory: string, sessionID: string, messageID: string) => void,
 ) {
   _sdk = sdk
   _childStores = childStores
   _getDirectory = getDirectory
+  _enqueueSessionMaterialization = enqueueSessionMaterialization ?? null
 }
 
 export function setOptimisticRefs(
@@ -480,6 +488,29 @@ function restoreFilePartsToInput(fileParts: Array<Record<string, unknown>>): voi
   }
 }
 
+/**
+ * Server-confirmed directory that owns a session, from the session record
+ * (`directory`, then `project.worktree`). Mirrors the authoritative source in
+ * session-directory-resolution: holding a session in a child store proves
+ * containment, not ownership — a project's session list legitimately includes
+ * the sessions of its worktrees so the sidebar can group them — so reading
+ * ownership from the containing store reports the parent for a session that
+ * lives in a worktree, and every fetch is then addressed to a directory that
+ * does not own it.
+ */
+function resolveSessionOwnedDirectory(session: Session): string | null {
+  const record = session as Session & {
+    directory?: string | null
+    project?: { worktree?: string | null } | null
+  }
+  const raw = typeof record.directory === "string" && record.directory.trim().length > 0
+    ? record.directory
+    : typeof record.project?.worktree === "string" && record.project.worktree.trim().length > 0
+      ? record.project.worktree
+      : null
+  return raw ? normalizePath(raw) : null
+}
+
 function resolveDirectoryForBlockingRequest(
   type: "permission" | "question",
   sessionId: string,
@@ -493,10 +524,28 @@ function resolveDirectoryForBlockingRequest(
   for (const [directory, store] of stores.children) {
     const state = store.getState()
     const requestMap = type === "permission" ? state.permission : state.question
-    for (const requests of Object.values(requestMap) as Array<Array<{ id: string }> | undefined>) {
-      if (requests?.some((request) => request.id === requestId)) {
-        return directory
-      }
+    for (const requests of Object.values(requestMap) as Array<Array<{ id: string; sessionID?: string }> | undefined>) {
+      const request = requests?.find((candidate) => candidate.id === requestId)
+      if (!request) continue
+
+      // Ownership beats containment. The request belongs to one specific
+      // session, and the reply must reach the instance that actually tracks
+      // it — the directory the session record's server-confirmed `directory`
+      // names. The containing store's key only proves containment: a project
+      // store holds its worktree sessions too, and a reply addressed to the
+      // parent instance makes the server answer QuestionNotFoundError while
+      // the question stays pending in the worktree instance, leaving the
+      // session stuck on the running question tool. Fall back to the store
+      // key only when the session record carries no directory.
+      const requestSessionID = typeof request.sessionID === "string" && request.sessionID.length > 0
+        ? request.sessionID
+        : sessionId
+      const sessionRecord = requestSessionID
+        ? state.session.find((s) => s.id === requestSessionID)
+        : undefined
+      const ownedDirectory = sessionRecord ? resolveSessionOwnedDirectory(sessionRecord) : null
+      if (ownedDirectory) return ownedDirectory
+      return directory
     }
   }
 
@@ -537,6 +586,38 @@ export function isQuestionRequestNotFoundError(error: unknown): boolean {
   return /Question(?:\.)?NotFoundError|Question request not found/i.test(message)
 }
 
+/**
+ * Reconcile the trailing assistant tool part after a blocking request turned
+ * out to be stale server-side (reply/reject answered with not-found). The
+ * local request is removed (the server no longer tracks it), but the
+ * question/permission tool part can remain `running` with the session busy —
+ * the UI would stay on "asking question" with no recovery until the user
+ * stops the run. Enqueue the sync layer's settled-running-tool tail
+ * materialization so the part converges to the server's actual state.
+ */
+function recoverStaleBlockingRequest(sessionId: string): void {
+  const stores = _childStores
+  const enqueue = _enqueueSessionMaterialization
+  if (!stores || !enqueue || !sessionId) return
+
+  for (const [directory, store] of stores.children) {
+    const state = store.getState()
+    if (
+      !state.session.some((session) => session.id === sessionId)
+      && !Object.prototype.hasOwnProperty.call(state.message, sessionId)
+      && !Object.prototype.hasOwnProperty.call(state.session_status ?? {}, sessionId)
+      && !Object.prototype.hasOwnProperty.call(state.question ?? {}, sessionId)
+    ) {
+      continue
+    }
+    const messageID = getStaleRunningToolMessageID(state, sessionId)
+    if (messageID) {
+      enqueue(directory, sessionId, messageID)
+    }
+    return
+  }
+}
+
 function removeQuestionRequestFromChildStores(sessionId: string, requestId: string): boolean {
   const stores = _childStores
   if (!stores || !requestId) return false
@@ -1581,6 +1662,7 @@ export async function respondToQuestion(
   } catch (error) {
     if (isQuestionRequestNotFoundError(error)) {
       removeQuestionRequestFromChildStores(sessionId, requestId)
+      recoverStaleBlockingRequest(sessionId)
     }
     throw error
   }
@@ -1605,6 +1687,7 @@ export async function rejectQuestion(
   } catch (error) {
     if (isQuestionRequestNotFoundError(error)) {
       removeQuestionRequestFromChildStores(sessionId, requestId)
+      recoverStaleBlockingRequest(sessionId)
     }
     throw error
   }
diff --git a/packages/ui/src/sync/sync-context.tsx b/packages/ui/src/sync/sync-context.tsx
index b4ff6c19..f3fb1610 100644
--- a/packages/ui/src/sync/sync-context.tsx
+++ b/packages/ui/src/sync/sync-context.tsx
@@ -2260,6 +2260,12 @@ export function SyncProvider(props: {
       props.sdk,
       childStores,
       () => opencodeClient.getDirectory() || props.directory,
+      (directory, sessionID, messageID) => {
+        enqueueSessionMaterialization(directory, sessionID, childStores, {
+          reason: "settled-running-tool",
+          messageID,
+        })
+      },
     )
     return () => {
       if (getImperativeSessionMessageLoader() === messageLoader) {

From ff5814a7313b794e4410f6c3dedaa340cb48a861 Mon Sep 17 00:00:00 2001
From: Serhii Dziupin <serkraser@gmail.com>
Date: Wed, 5 Aug 2026 11:48:31 +0300
Subject: [PATCH 20/57] fix(web): parse agent frontmatter as leniently as
 OpenCode

parseMdFile now matches gray-matter (used by OpenCode) for file shapes
OpenChamber previously failed to parse: frontmatter whose closing '---'
sits at end-of-file without a trailing newline, a UTF-8 BOM prefix, and
YAML with unquoted colons in scalar values (via the same sanitizer
OpenCode applies). OpenCode parses these files, so OpenChamber must
too: otherwise the whole file was treated as the prompt body and a
save rewrote the existing YAML block into the body, prepending a
duplicate frontmatter block.

Refs OPE-178
---
 packages/web/server/lib/opencode/shared.js    |  41 +++-
 .../web/server/lib/opencode/shared.test.js    | 202 ++++++++++++++++++
 2 files changed, 239 insertions(+), 4 deletions(-)
 create mode 100644 packages/web/server/lib/opencode/shared.test.js

diff --git a/packages/web/server/lib/opencode/shared.js b/packages/web/server/lib/opencode/shared.js
index 6df1faea..062d3d0f 100644
--- a/packages/web/server/lib/opencode/shared.js
+++ b/packages/web/server/lib/opencode/shared.js
@@ -49,9 +49,36 @@ function ensureDirs() {
 
 // ============== MARKDOWN FILE OPERATIONS ==============
 
+// Mirror of OpenCode's markdown frontmatter sanitizer (packages/opencode/src/
+// config/markdown.ts): other coding agents accept unquoted colons in YAML
+// values (e.g. `description: Build agent: creates builds`), which strict YAML
+// rejects. Rewrite those values as block scalars and retry the parse, so files
+// OpenCode accepts are parsed identically here.
+function sanitizeFrontmatter(frontmatter) {
+  return frontmatter
+    .split(/\r?\n/)
+    .flatMap((line) => {
+      if (line.trim().startsWith('#') || line.trim() === '' || /^\s+/.test(line)) return [line];
+      const entry = line.match(/^([a-zA-Z_][a-zA-Z0-9_]*)\s*:\s*(.*)$/);
+      if (!entry) return [line];
+      const value = entry[2].trim();
+      if (value === '' || value === '>' || value === '|' || value.startsWith('"') || value.startsWith("'")) return [line];
+      if (!value.includes(':')) return [line];
+      return [`${entry[1]}: |-`, `  ${value}`];
+    })
+    .join('\n');
+}
+
 function parseMdFile(filePath) {
-  const content = fs.readFileSync(filePath, 'utf8');
-  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
+  const rawContent = fs.readFileSync(filePath, 'utf8');
+  // Strip a UTF-8 BOM so frontmatter is recognized regardless of the editor
+  // that saved the file.
+  const content = rawContent.charCodeAt(0) === 0xfeff ? rawContent.slice(1) : rawContent;
+  // The closing `---` may sit at end-of-file without a trailing newline.
+  // gray-matter (used by OpenCode) accepts that, so we must too: otherwise the
+  // whole file is treated as the prompt body and a later save rewrites the
+  // existing YAML block into the body, duplicating the frontmatter.
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)([\s\S]*)$/);
 
   if (!match) {
     return { frontmatter: {}, body: content.trim() };
@@ -61,8 +88,14 @@ function parseMdFile(filePath) {
   try {
     frontmatter = yaml.parse(match[1]) || {};
   } catch (error) {
-    console.warn(`Failed to parse markdown frontmatter ${filePath}, treating as empty:`, error);
-    frontmatter = {};
+    // Lenient fallback for frontmatter that strict YAML rejects but OpenCode
+    // still accepts (unquoted colons in scalar values).
+    try {
+      frontmatter = yaml.parse(sanitizeFrontmatter(match[1])) || {};
+    } catch {
+      console.warn(`Failed to parse markdown frontmatter ${filePath}, treating as empty:`, error);
+      frontmatter = {};
+    }
   }
 
   const body = match[2].trim();
diff --git a/packages/web/server/lib/opencode/shared.test.js b/packages/web/server/lib/opencode/shared.test.js
new file mode 100644
index 00000000..e131aa0c
--- /dev/null
+++ b/packages/web/server/lib/opencode/shared.test.js
@@ -0,0 +1,202 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+import { parseMdFile, writeMdFile } from './shared.js';
+import { updateAgent } from './agents.js';
+
+const FIXTURE_DIR = path.join(os.tmpdir(), `openchamber-shared-test-${process.pid}`);
+
+const STANDARD_MD = [
+  '---',
+  'description: My build agent',
+  'model: anthropic/claude-sonnet-4',
+  'mode: primary',
+  '---',
+  '',
+  'This is the prompt body.',
+  '',
+].join('\n');
+
+const writeFixture = (name, content) => {
+  const filePath = path.join(FIXTURE_DIR, name);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content, 'utf8');
+  return filePath;
+};
+
+describe('parseMdFile', () => {
+  beforeEach(() => {
+    fs.rmSync(FIXTURE_DIR, { recursive: true, force: true });
+    fs.mkdirSync(FIXTURE_DIR, { recursive: true });
+  });
+
+  afterEach(() => {
+    fs.rmSync(FIXTURE_DIR, { recursive: true, force: true });
+  });
+
+  it('parses standard YAML frontmatter', () => {
+    const file = writeFixture('standard.md', STANDARD_MD);
+    const { frontmatter, body } = parseMdFile(file);
+    expect(frontmatter).toEqual({
+      description: 'My build agent',
+      model: 'anthropic/claude-sonnet-4',
+      mode: 'primary',
+    });
+    expect(body).toBe('This is the prompt body.');
+  });
+
+  it('parses frontmatter whose closing --- is at end-of-file without a trailing newline', () => {
+    // gray-matter (used by OpenCode) accepts this shape; OpenChamber must too,
+    // otherwise a later save duplicates the YAML block.
+    const file = writeFixture('eof-close.md', [
+      '---',
+      'description: My build agent',
+      'model: anthropic/claude-sonnet-4',
+      '---',
+    ].join('\n'));
+    const { frontmatter, body } = parseMdFile(file);
+    expect(frontmatter).toEqual({
+      description: 'My build agent',
+      model: 'anthropic/claude-sonnet-4',
+    });
+    expect(body).toBe('');
+  });
+
+  it('parses frontmatter with CRLF line endings', () => {
+    const file = writeFixture('crlf.md', STANDARD_MD.replace(/\n/g, '\r\n'));
+    const { frontmatter, body } = parseMdFile(file);
+    expect(frontmatter.model).toBe('anthropic/claude-sonnet-4');
+    expect(body).toBe('This is the prompt body.');
+  });
+
+  it('parses frontmatter preceded by a UTF-8 BOM', () => {
+    const file = writeFixture('bom.md', `\uFEFF${STANDARD_MD}`);
+    const { frontmatter, body } = parseMdFile(file);
+    expect(frontmatter.description).toBe('My build agent');
+    expect(body).toBe('This is the prompt body.');
+  });
+
+  it('falls back to lenient YAML for unquoted colons in values, matching OpenCode', () => {
+    const file = writeFixture('colon.md', [
+      '---',
+      'description: Build agent: creates builds',
+      'model: anthropic/claude-sonnet-4',
+      '---',
+      '',
+      'Body',
+      '',
+    ].join('\n'));
+    const { frontmatter, body } = parseMdFile(file);
+    expect(frontmatter).toEqual({
+      description: 'Build agent: creates builds',
+      model: 'anthropic/claude-sonnet-4',
+    });
+    expect(body).toBe('Body');
+  });
+
+  it('treats files without frontmatter as a plain body', () => {
+    const file = writeFixture('plain.md', 'Just a prompt body.');
+    const { frontmatter, body } = parseMdFile(file);
+    expect(frontmatter).toEqual({});
+    expect(body).toBe('Just a prompt body.');
+  });
+});
+
+describe('writeMdFile', () => {
+  beforeEach(() => {
+    fs.rmSync(FIXTURE_DIR, { recursive: true, force: true });
+    fs.mkdirSync(FIXTURE_DIR, { recursive: true });
+  });
+
+  afterEach(() => {
+    fs.rmSync(FIXTURE_DIR, { recursive: true, force: true });
+  });
+
+  it('round-trips a canonical single frontmatter block', () => {
+    const file = writeFixture('roundtrip.md', STANDARD_MD);
+    const parsed = parseMdFile(file);
+    parsed.frontmatter.model = 'openai/gpt-5';
+    writeMdFile(file, parsed.frontmatter, parsed.body);
+
+    const content = fs.readFileSync(file, 'utf8');
+    // Exactly one frontmatter block.
+    expect(content.match(/^---\r?\n/g)).toHaveLength(1);
+
+    const reparsed = parseMdFile(file);
+    expect(reparsed.frontmatter).toEqual({
+      description: 'My build agent',
+      model: 'openai/gpt-5',
+      mode: 'primary',
+    });
+    expect(reparsed.body).toBe('This is the prompt body.');
+  });
+});
+
+describe('updateAgent frontmatter preservation', () => {
+  beforeEach(() => {
+    fs.rmSync(FIXTURE_DIR, { recursive: true, force: true });
+    fs.mkdirSync(FIXTURE_DIR, { recursive: true });
+  });
+
+  afterEach(() => {
+    fs.rmSync(FIXTURE_DIR, { recursive: true, force: true });
+  });
+
+  it('updates the model in place without duplicating YAML for a file with EOF-closed frontmatter', () => {
+    // Repro of OPE-178: the file's closing --- sits at EOF (no trailing
+    // newline). OpenCode parses it; OpenChamber previously treated the whole
+    // file as the prompt body and prepended a second frontmatter block on save.
+    const projectDir = path.join(FIXTURE_DIR, 'project');
+    const agentPath = path.join(projectDir, '.opencode', 'agents', 'strateg.md');
+    writeFixture(path.join('project', '.opencode', 'agents', 'strateg.md'), [
+      '---',
+      'description: Strategy agent',
+      'model: anthropic/claude-sonnet-4',
+      'temperature: 0.7',
+      '---',
+    ].join('\n'));
+
+    updateAgent('strateg', { model: 'openai/gpt-5' }, projectDir);
+
+    const content = fs.readFileSync(agentPath, 'utf8');
+    expect(content.match(/^---\r?\n/g)).toHaveLength(1);
+
+    const parsed = parseMdFile(agentPath);
+    expect(parsed.frontmatter).toEqual({
+      description: 'Strategy agent',
+      model: 'openai/gpt-5',
+      temperature: 0.7,
+    });
+    expect(parsed.body).toBe('');
+  });
+
+  it('preserves unrelated frontmatter fields when saving one field', () => {
+    const projectDir = path.join(FIXTURE_DIR, 'project');
+    const agentPath = path.join(projectDir, '.opencode', 'agents', 'strateg.md');
+    writeFixture(path.join('project', '.opencode', 'agents', 'strateg.md'), [
+      '---',
+      'description: Strategy agent',
+      'mode: primary',
+      'temperature: 0.7',
+      '---',
+      '',
+      'Body of strateg.',
+      '',
+    ].join('\n'));
+
+    updateAgent('strateg', { description: 'Updated strategy agent' }, projectDir);
+
+    const content = fs.readFileSync(agentPath, 'utf8');
+    expect(content.match(/^---\r?\n/g)).toHaveLength(1);
+
+    const parsed = parseMdFile(agentPath);
+    expect(parsed.frontmatter).toEqual({
+      description: 'Updated strategy agent',
+      mode: 'primary',
+      temperature: 0.7,
+    });
+    expect(parsed.body).toBe('Body of strateg.');
+  });
+});

From 654e9cdb64e56f3a05108cdaabd2a7e12c164687 Mon Sep 17 00:00:00 2001
From: Serhii Dziupin <serkraser@gmail.com>
Date: Wed, 5 Aug 2026 13:37:20 +0300
Subject: [PATCH 21/57] feat(chat): refocus composer after adding message to
 context

After the add-to-context (context pin) action completes successfully, move
focus back to the chat input so the user can keep typing immediately. Uses
the existing focusChatInput helper and the requestAnimationFrame refocus
pattern already used by the model/agent selectors.

Fixes #2447
---
 packages/ui/src/components/chat/ChatMessage.tsx | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/packages/ui/src/components/chat/ChatMessage.tsx b/packages/ui/src/components/chat/ChatMessage.tsx
index 5b45b4b3..5ec9a8ac 100644
--- a/packages/ui/src/components/chat/ChatMessage.tsx
+++ b/packages/ui/src/components/chat/ChatMessage.tsx
@@ -37,6 +37,7 @@ import { useGlobalSessionsStore } from '@/stores/useGlobalSessionsStore';
 import { getContextObligatoryMessages } from '@/lib/contextObligatoryMessages';
 import { setContextObligatoryMessage } from '@/sync/session-actions';
 import { isVSCodeRuntime } from '@/lib/desktop';
+import { focusChatInput } from './composer/editor/dom';
 
 const ToolOutputDialog = lazyWithChunkRecovery(() => import('./message/ToolOutputDialog'));
 
@@ -416,6 +417,10 @@ const ChatMessage: React.FC<ChatMessageProps> = ({
                 createdAt: messageCreatedAt,
                 role: isUser ? 'user' : 'assistant',
             }, !isPinnedIntoContext);
+            // Return focus to the composer so the user can keep typing right
+            // after adding the message to context (matches the refocus pattern
+            // used by the model/agent selectors).
+            requestAnimationFrame(focusChatInput);
         } catch (error) {
             console.error('[chat-message] failed to update context pin', error);
             toast.error(t('chat.messageBody.actions.contextPinFailed'));

From 9b7c03252436881fbe849662a36e9cb46a9af817 Mon Sep 17 00:00:00 2001
From: Serhii Dziupin <serkraser@gmail.com>
Date: Wed, 5 Aug 2026 13:37:46 +0300
Subject: [PATCH 22/57] feat(ui): show the changed-files count badge on the Git
 rail surface

Replaces the plain activity dot on the context panel rail's Git button with
a numeric badge of the changed-files count from the git store status, so the
count is visible at a glance without opening the Git surface. Large counts
cap at 99+ to keep the pill within the 36px button. The badge is reflected
in the button's accessible label and the hover tooltip.

Fixes #2364
---
 .../components/layout/ContextPanelRail.tsx    | 78 ++++++++++++++-----
 packages/ui/src/lib/i18n/messages/de.ts       |  2 +
 packages/ui/src/lib/i18n/messages/en.ts       |  2 +
 packages/ui/src/lib/i18n/messages/es.ts       |  2 +
 packages/ui/src/lib/i18n/messages/fr.ts       |  2 +
 packages/ui/src/lib/i18n/messages/ja.ts       |  2 +
 packages/ui/src/lib/i18n/messages/ko.ts       |  2 +
 packages/ui/src/lib/i18n/messages/pl.ts       |  2 +
 packages/ui/src/lib/i18n/messages/pt-BR.ts    |  2 +
 packages/ui/src/lib/i18n/messages/uk.ts       |  2 +
 packages/ui/src/lib/i18n/messages/zh-CN.ts    |  2 +
 packages/ui/src/lib/i18n/messages/zh-TW.ts    |  2 +
 12 files changed, 80 insertions(+), 20 deletions(-)

diff --git a/packages/ui/src/components/layout/ContextPanelRail.tsx b/packages/ui/src/components/layout/ContextPanelRail.tsx
index 43692cbb..54b5d78c 100644
--- a/packages/ui/src/components/layout/ContextPanelRail.tsx
+++ b/packages/ui/src/components/layout/ContextPanelRail.tsx
@@ -49,17 +49,30 @@ type RailItemProps = {
   showActivityDot: boolean;
   label: string;
   description: string;
+  /** Numeric badge (e.g. the Git changed-files count); takes precedence over the activity dot. */
+  badgeCount?: number | null;
+  /** Accessible label that includes the badge count; falls back to `label`. */
+  badgeAriaLabel?: string | null;
+  /** Extra tooltip line describing the badge; rendered under the description. */
+  badgeDescription?: string | null;
   orderNumber?: number | null;
   showOrderNumber?: boolean;
   onSelect: (surface: ContextSurfaceDescriptor) => void;
 };
 
+// The badge corner is 16px tall; cap large counts so the pill stays compact
+// on the 36px rail button (matching the order-number badge's footprint).
+const formatRailBadgeCount = (count: number): string => (count > 99 ? '99+' : String(count));
+
 const ContextPanelRailItem: React.FC<RailItemProps> = ({
   surface,
   isActive,
   showActivityDot,
   label,
   description,
+  badgeCount,
+  badgeAriaLabel,
+  badgeDescription,
   orderNumber,
   showOrderNumber,
   onSelect,
@@ -68,6 +81,8 @@ const ContextPanelRailItem: React.FC<RailItemProps> = ({
     id: surface.id,
   });
 
+  const displayBadgeCount = badgeCount != null && badgeCount > 0 ? formatRailBadgeCount(badgeCount) : null;
+
   return (
     <div
       ref={setNodeRef}
@@ -81,7 +96,7 @@ const ContextPanelRailItem: React.FC<RailItemProps> = ({
             {...attributes}
             {...listeners}
             onClick={() => onSelect(surface)}
-            aria-label={label}
+            aria-label={badgeAriaLabel ?? label}
             aria-pressed={isActive}
             className={cn(
               'flex h-9 w-9 touch-none select-none items-center justify-center rounded-md transition-colors',
@@ -95,12 +110,6 @@ const ContextPanelRailItem: React.FC<RailItemProps> = ({
             ) : (
               <Icon name={surface.icon} className="h-[18px] w-[18px]" />
             )}
-            {showActivityDot && !showOrderNumber ? (
-              <span
-                aria-hidden="true"
-                className="absolute right-1 top-1 h-1.5 w-1.5 rounded-full bg-[var(--status-info)]"
-              />
-            ) : null}
             {showOrderNumber && orderNumber != null ? (
               <span
                 aria-hidden="true"
@@ -108,6 +117,18 @@ const ContextPanelRailItem: React.FC<RailItemProps> = ({
               >
                 {orderNumber === 10 ? '0' : orderNumber}
               </span>
+            ) : displayBadgeCount ? (
+              <span
+                aria-hidden="true"
+                className="absolute right-0 top-0 flex h-4 min-w-4 items-center justify-center rounded-full bg-surface-muted px-1 text-[0.625rem] font-medium leading-none text-muted-foreground"
+              >
+                {displayBadgeCount}
+              </span>
+            ) : showActivityDot ? (
+              <span
+                aria-hidden="true"
+                className="absolute right-1 top-1 h-1.5 w-1.5 rounded-full bg-[var(--status-info)]"
+              />
             ) : null}
           </button>
         </TooltipTrigger>
@@ -115,6 +136,9 @@ const ContextPanelRailItem: React.FC<RailItemProps> = ({
           <div className="flex flex-col gap-0.5">
             <span>{label}</span>
             <span className="typography-micro text-muted-foreground">{description}</span>
+            {badgeDescription ? (
+              <span className="typography-micro text-muted-foreground">{badgeDescription}</span>
+            ) : null}
           </div>
         </TooltipContent>
       </Tooltip>
@@ -258,19 +282,33 @@ export const ContextPanelRail: React.FC = () => {
     >
       <DndContext sensors={sensors} collisionDetection={closestCenter} onDragEnd={handleDragEnd}>
         <SortableContext items={surfaces.map((surface) => surface.id)} strategy={verticalListSortingStrategy}>
-          {surfaces.map((surface, index) => (
-            <ContextPanelRailItem
-              key={surface.id}
-              surface={surface}
-              isActive={activeMode === surface.mode}
-              showActivityDot={surface.id === 'git' && changedFilesCount > 0}
-              label={t(surface.labelKey)}
-              description={t(surface.descriptionKey)}
-              orderNumber={index + 1}
-              showOrderNumber={revealNumbers}
-              onSelect={(selected) => openContextSurface(directoryKey, selected.mode)}
-            />
-          ))}
+          {surfaces.map((surface, index) => {
+            const label = t(surface.labelKey);
+            // The Git surface carries its changed-files count as a numeric
+            // badge; other surfaces keep the plain activity dot.
+            const gitChangedCount = surface.id === 'git' ? changedFilesCount : 0;
+            const badgeCount = gitChangedCount > 0 ? gitChangedCount : null;
+            return (
+              <ContextPanelRailItem
+                key={surface.id}
+                surface={surface}
+                isActive={activeMode === surface.mode}
+                showActivityDot={surface.id !== 'git' && changedFilesCount > 0}
+                label={label}
+                description={t(surface.descriptionKey)}
+                badgeCount={badgeCount}
+                badgeAriaLabel={badgeCount !== null
+                  ? t('contextRail.surface.git.changesCountAria', { label, count: badgeCount })
+                  : null}
+                badgeDescription={badgeCount !== null
+                  ? t('contextRail.surface.git.changesCountTooltip', { count: badgeCount })
+                  : null}
+                orderNumber={index + 1}
+                showOrderNumber={revealNumbers}
+                onSelect={(selected) => openContextSurface(directoryKey, selected.mode)}
+              />
+            );
+          })}
         </SortableContext>
       </DndContext>
     </nav>
diff --git a/packages/ui/src/lib/i18n/messages/de.ts b/packages/ui/src/lib/i18n/messages/de.ts
index 57a22de2..ffa3702f 100644
--- a/packages/ui/src/lib/i18n/messages/de.ts
+++ b/packages/ui/src/lib/i18n/messages/de.ts
@@ -2828,6 +2828,8 @@ export const dict = {
   'contextPanel.editorEmpty.description': 'Wählen Sie etwas aus der Seitenleiste aus, um Kontext anzuzeigen.',
   'contextRail.surface.editor.description': 'Bearbeitungskontext',
   'contextRail.surface.git.description': 'Git-Kontext',
+  'contextRail.surface.git.changesCountAria': '{label}, {count} geänderte Dateien',
+  'contextRail.surface.git.changesCountTooltip': '{count} geänderte Dateien',
   'contextRail.surface.terminal.description': 'Terminal-Kontext',
   'contextRail.surface.diff.description': 'Diff-Kontext',
   'contextPanel.mode.walkthrough': 'Walkthrough',
diff --git a/packages/ui/src/lib/i18n/messages/en.ts b/packages/ui/src/lib/i18n/messages/en.ts
index c77d6a07..641e4944 100644
--- a/packages/ui/src/lib/i18n/messages/en.ts
+++ b/packages/ui/src/lib/i18n/messages/en.ts
@@ -1106,6 +1106,8 @@ export const dict = {
   'contextPanel.editorEmpty.description': 'Pick a file from the tree to start editing.',
   'contextRail.surface.editor.description': 'Edit project files',
   'contextRail.surface.git.description': 'Commits, branches, and pull requests',
+  'contextRail.surface.git.changesCountAria': '{label}, {count} changed files',
+  'contextRail.surface.git.changesCountTooltip': '{count} changed files',
   'contextRail.surface.terminal.description': 'Built-in terminal',
   'contextRail.surface.diff.description': 'Review working changes',
   'contextPanel.mode.walkthrough': 'Walkthrough',
diff --git a/packages/ui/src/lib/i18n/messages/es.ts b/packages/ui/src/lib/i18n/messages/es.ts
index 72985914..a125d533 100644
--- a/packages/ui/src/lib/i18n/messages/es.ts
+++ b/packages/ui/src/lib/i18n/messages/es.ts
@@ -1107,6 +1107,8 @@ export const dict: Record<I18nKey, string> = {
   "contextPanel.editorEmpty.description": "Elige un archivo del árbol para empezar a editar.",
   "contextRail.surface.editor.description": "Editar archivos del proyecto",
   "contextRail.surface.git.description": "Commits, ramas y pull requests",
+  "contextRail.surface.git.changesCountAria": "{label}, {count} archivos modificados",
+  "contextRail.surface.git.changesCountTooltip": "{count} archivos modificados",
   "contextRail.surface.terminal.description": "Terminal integrada",
   "contextRail.surface.diff.description": "Revisar cambios en curso",
   "contextPanel.mode.walkthrough": "Recorrido",
diff --git a/packages/ui/src/lib/i18n/messages/fr.ts b/packages/ui/src/lib/i18n/messages/fr.ts
index 986a4cd4..1fa0637e 100644
--- a/packages/ui/src/lib/i18n/messages/fr.ts
+++ b/packages/ui/src/lib/i18n/messages/fr.ts
@@ -931,6 +931,8 @@ export const dict = {
   'contextPanel.editorEmpty.description': 'Choisissez un fichier dans l’arborescence pour commencer.',
   'contextRail.surface.editor.description': 'Modifier les fichiers du projet',
   'contextRail.surface.git.description': 'Commits, branches et pull requests',
+  'contextRail.surface.git.changesCountAria': '{label}, {count} fichiers modifiés',
+  'contextRail.surface.git.changesCountTooltip': '{count} fichiers modifiés',
   'contextRail.surface.terminal.description': 'Terminal intégré',
   'contextRail.surface.diff.description': 'Passer en revue les modifications',
   'contextPanel.mode.walkthrough': 'Parcours',
diff --git a/packages/ui/src/lib/i18n/messages/ja.ts b/packages/ui/src/lib/i18n/messages/ja.ts
index 0f4da4e7..83d7fb32 100644
--- a/packages/ui/src/lib/i18n/messages/ja.ts
+++ b/packages/ui/src/lib/i18n/messages/ja.ts
@@ -1103,6 +1103,8 @@ export const dict: Record<I18nKey, string> = {
   'contextPanel.editorEmpty.description': 'ツリーからファイルを選んで編集を始めましょう。',
   'contextRail.surface.editor.description': 'プロジェクトのファイルを編集',
   'contextRail.surface.git.description': 'コミット・ブランチ・プルリクエスト',
+  'contextRail.surface.git.changesCountAria': '{label}、変更ファイル{count}件',
+  'contextRail.surface.git.changesCountTooltip': '変更ファイル{count}件',
   'contextRail.surface.terminal.description': '内蔵ターミナル',
   'contextRail.surface.diff.description': '作業中の変更をレビュー',
   'contextPanel.mode.walkthrough': 'ウォークスルー',
diff --git a/packages/ui/src/lib/i18n/messages/ko.ts b/packages/ui/src/lib/i18n/messages/ko.ts
index 0f09fba2..986ff3bd 100644
--- a/packages/ui/src/lib/i18n/messages/ko.ts
+++ b/packages/ui/src/lib/i18n/messages/ko.ts
@@ -1107,6 +1107,8 @@ export const dict: Record<I18nKey, string> = {
   'contextPanel.editorEmpty.description': '트리에서 파일을 선택해 편집을 시작하세요.',
   'contextRail.surface.editor.description': '프로젝트 파일 편집',
   'contextRail.surface.git.description': '커밋, 브랜치, 풀 리퀘스트',
+  'contextRail.surface.git.changesCountAria': '{label}, 변경된 파일 {count}개',
+  'contextRail.surface.git.changesCountTooltip': '변경된 파일 {count}개',
   'contextRail.surface.terminal.description': '내장 터미널',
   'contextRail.surface.diff.description': '작업 중인 변경 사항 검토',
   'contextPanel.mode.walkthrough': '워크스루',
diff --git a/packages/ui/src/lib/i18n/messages/pl.ts b/packages/ui/src/lib/i18n/messages/pl.ts
index 12f727b1..ad308b23 100644
--- a/packages/ui/src/lib/i18n/messages/pl.ts
+++ b/packages/ui/src/lib/i18n/messages/pl.ts
@@ -1419,6 +1419,8 @@ export const dict: Record<I18nKey, string> = {
   'contextPanel.editorEmpty.description': 'Wybierz plik z drzewa, aby rozpocząć edycję.',
   'contextRail.surface.editor.description': 'Edytuj pliki projektu',
   'contextRail.surface.git.description': 'Commity, gałęzie i pull requesty',
+  'contextRail.surface.git.changesCountAria': '{label}, {count} zmienionych plików',
+  'contextRail.surface.git.changesCountTooltip': '{count} zmienionych plików',
   'contextRail.surface.terminal.description': 'Wbudowany terminal',
   'contextRail.surface.diff.description': 'Przeglądaj bieżące zmiany',
   'contextPanel.mode.walkthrough': 'Przewodnik',
diff --git a/packages/ui/src/lib/i18n/messages/pt-BR.ts b/packages/ui/src/lib/i18n/messages/pt-BR.ts
index 10dd7709..d2e16295 100644
--- a/packages/ui/src/lib/i18n/messages/pt-BR.ts
+++ b/packages/ui/src/lib/i18n/messages/pt-BR.ts
@@ -1107,6 +1107,8 @@ export const dict: Record<I18nKey, string> = {
   "contextPanel.editorEmpty.description": "Escolha um arquivo na árvore para começar a editar.",
   "contextRail.surface.editor.description": "Editar arquivos do projeto",
   "contextRail.surface.git.description": "Commits, branches e pull requests",
+  "contextRail.surface.git.changesCountAria": "{label}, {count} arquivos modificados",
+  "contextRail.surface.git.changesCountTooltip": "{count} arquivos modificados",
   "contextRail.surface.terminal.description": "Terminal integrado",
   "contextRail.surface.diff.description": "Revisar alterações em andamento",
   "contextPanel.mode.walkthrough": "Percurso",
diff --git a/packages/ui/src/lib/i18n/messages/uk.ts b/packages/ui/src/lib/i18n/messages/uk.ts
index dd52bcb9..4e61c8f5 100644
--- a/packages/ui/src/lib/i18n/messages/uk.ts
+++ b/packages/ui/src/lib/i18n/messages/uk.ts
@@ -1107,6 +1107,8 @@ export const dict: Record<I18nKey, string> = {
   "contextPanel.editorEmpty.description": "Виберіть файл у дереві, щоб почати редагування.",
   "contextRail.surface.editor.description": "Редагування файлів проєкту",
   "contextRail.surface.git.description": "Коміти, гілки та pull request-и",
+  "contextRail.surface.git.changesCountAria": "{label}, {count} змінених файлів",
+  "contextRail.surface.git.changesCountTooltip": "{count} змінених файлів",
   "contextRail.surface.terminal.description": "Вбудований термінал",
   "contextRail.surface.diff.description": "Перегляд поточних змін",
   "contextPanel.mode.walkthrough": "Розбір",
diff --git a/packages/ui/src/lib/i18n/messages/zh-CN.ts b/packages/ui/src/lib/i18n/messages/zh-CN.ts
index 35de2c9c..4d262c92 100644
--- a/packages/ui/src/lib/i18n/messages/zh-CN.ts
+++ b/packages/ui/src/lib/i18n/messages/zh-CN.ts
@@ -1107,6 +1107,8 @@ export const dict: Record<I18nKey, string> = {
   'contextPanel.editorEmpty.description': '从文件树中选择一个文件开始编辑。',
   'contextRail.surface.editor.description': '编辑项目文件',
   'contextRail.surface.git.description': '提交、分支和拉取请求',
+  'contextRail.surface.git.changesCountAria': '{label}，{count} 个更改的文件',
+  'contextRail.surface.git.changesCountTooltip': '{count} 个更改的文件',
   'contextRail.surface.terminal.description': '内置终端',
   'contextRail.surface.diff.description': '查看工作区更改',
   'contextPanel.mode.walkthrough': '导读',
diff --git a/packages/ui/src/lib/i18n/messages/zh-TW.ts b/packages/ui/src/lib/i18n/messages/zh-TW.ts
index 6641606b..e323ed7f 100644
--- a/packages/ui/src/lib/i18n/messages/zh-TW.ts
+++ b/packages/ui/src/lib/i18n/messages/zh-TW.ts
@@ -1119,6 +1119,8 @@ export const dict: Record<I18nKey, string> = {
   'contextPanel.editorEmpty.description': '從檔案樹選擇檔案開始編輯。',
   'contextRail.surface.editor.description': '編輯專案檔案',
   'contextRail.surface.git.description': '提交、分支與拉取請求',
+  'contextRail.surface.git.changesCountAria': '{label}，{count} 個變更的檔案',
+  'contextRail.surface.git.changesCountTooltip': '{count} 個變更的檔案',
   'contextRail.surface.terminal.description': '內建終端機',
   'contextRail.surface.diff.description': '檢視工作區變更',
   'contextPanel.mode.walkthrough': '導讀',

From c1ba6319647af2aa41240aebbc858bbc32f03ad0 Mon Sep 17 00:00:00 2001
From: Serhii Dziupin <serkraser@gmail.com>
Date: Wed, 5 Aug 2026 13:41:48 +0300
Subject: [PATCH 23/57] feat(sessions): show a pending-question indicator on
 session rows

Adds a per-session pending-question badge to sidebar rows, driven by the
live directory-store question state through a dedicated per-session
subscription channel so unrelated streaming never re-renders rows.

Collapsed parent rows roll up pending questions of hidden descendants
from their owning directory stores without bootstrapping them. Question
state is cloned on session delete/archive so badges clear when sessions
disappear. Adds the questionChangeCallbacks sync performance counter,
i18n keys for all locales, and unit tests for the subscription channel
and scope selection.

Fixes #2634
---
 .../session/sidebar/DOCUMENTATION.md          |   2 +-
 .../session/sidebar/SessionNodeItem.tsx       |  18 ++-
 .../sidebar/sessionNodeItemUtils.test.ts      |  37 ++++-
 .../session/sidebar/sessionNodeItemUtils.ts   |  37 +++++
 packages/ui/src/lib/i18n/messages/de.ts       |   2 +
 packages/ui/src/lib/i18n/messages/en.ts       |   2 +
 packages/ui/src/lib/i18n/messages/es.ts       |   2 +
 packages/ui/src/lib/i18n/messages/fr.ts       |   2 +
 packages/ui/src/lib/i18n/messages/ja.ts       |   2 +
 packages/ui/src/lib/i18n/messages/ko.ts       |   2 +
 packages/ui/src/lib/i18n/messages/pl.ts       |   2 +
 packages/ui/src/lib/i18n/messages/pt-BR.ts    |   2 +
 packages/ui/src/lib/i18n/messages/uk.ts       |   2 +
 packages/ui/src/lib/i18n/messages/zh-CN.ts    |   2 +
 packages/ui/src/lib/i18n/messages/zh-TW.ts    |   2 +
 packages/ui/src/sync/DOCUMENTATION.md         |   4 +-
 packages/ui/src/sync/child-store.test.ts      | 128 ++++++++++++++++++
 packages/ui/src/sync/child-store.ts           |  67 +++++++--
 .../ui/src/sync/performance-diagnostics.ts    |   2 +
 packages/ui/src/sync/sync-context.tsx         |  47 +++++++
 20 files changed, 343 insertions(+), 21 deletions(-)

diff --git a/packages/ui/src/components/session/sidebar/DOCUMENTATION.md b/packages/ui/src/components/session/sidebar/DOCUMENTATION.md
index 4033b4b8..180dd7f0 100644
--- a/packages/ui/src/components/session/sidebar/DOCUMENTATION.md
+++ b/packages/ui/src/components/session/sidebar/DOCUMENTATION.md
@@ -32,7 +32,7 @@
 - `SidebarFooter.tsx`: Static footer with icon-only settings, shortcuts, and about actions.
 - `SidebarProjectsList.tsx`: Main scrollable renderer for project zones and their flat/archived groups plus empty/search states; owns project drag-to-reorder.
 - `SessionGroupSection.tsx`: Renders one flat (or archived) group: sessions first, then flat folder entries with path labels, show-more batching, and explicit loading/error/retry state for empty groups. Archived buckets (VS Code) virtualize past 50 rows.
-- `SessionNodeItem.tsx`: Renders one session row/tree node with a single-line layout, inline branch label, indicators, menu actions, and nested children. Rows do not initiate directory bootstrap on mount.
+- `SessionNodeItem.tsx`: Renders one session row/tree node with a single-line layout, inline branch label, indicators, menu actions, and nested children. Pending-question counts stay per-session while expanded and roll up hidden descendants from their owning directory stores while collapsed. Rows do not initiate directory bootstrap on mount.
 - `collapsedActivityIndicator.tsx`: Aggregate busy/unseen dot for collapsed groups and folders.
 - `ConfirmDialogs.tsx`: Shared confirm dialog wrappers for session delete and folder delete flows.
 - `sortableItems.tsx`: DnD sortable wrapper for project ordering plus the sticky zone-band project header and its action affordances.
diff --git a/packages/ui/src/components/session/sidebar/SessionNodeItem.tsx b/packages/ui/src/components/session/sidebar/SessionNodeItem.tsx
index 6521feba..3b61d2a0 100644
--- a/packages/ui/src/components/session/sidebar/SessionNodeItem.tsx
+++ b/packages/ui/src/components/session/sidebar/SessionNodeItem.tsx
@@ -22,11 +22,11 @@ import { isSessionPinned, type SessionPinnedTarget } from '@/stores/useSessionPi
 import { Icon } from "@/components/icon/Icon";
 import { buildExportFilename, downloadAsMarkdown, formatSessionAsMarkdown, getExportRevealLabelKey, revealExportedMarkdown, saveAsMarkdownDesktop } from '@/lib/exportSession';
 import type { ChildSessionExport } from '@/lib/exportSession';
-import { buildSessionMessageRecordsSnapshot, useDirectoryStore, useGlobalSessionStatus, useSessionPermissions } from '@/sync/sync-context';
+import { buildSessionMessageRecordsSnapshot, useDirectoryStore, useGlobalSessionStatus, useSessionPermissions, useSessionQuestionCount } from '@/sync/sync-context';
 import { useSync } from '@/sync/use-sync';
 import { useViewportStore, viewportSessionKey } from '@/sync/viewport-store';
 import { DraggableSessionRow } from './sessionFolderDnd';
-import { nodeContainsSessionId, nodeHasPinnedMembershipChange } from './sessionNodeItemUtils';
+import { nodeContainsSessionId, nodeHasPinnedMembershipChange, selectQuestionBadgeSessionScopes } from './sessionNodeItemUtils';
 import type { SessionNodeChildRenderExtras, SessionNodeRenderExtras } from './sessionNodeItemUtils';
 import type { SessionNode } from './types';
 import { formatProjectLabel, formatSessionCompactDateLabel, formatSessionDateLabel, normalizePath, renderHighlightedText } from './utils';
@@ -470,6 +470,11 @@ function SessionNodeItemComponent(props: Props): React.ReactNode {
   // expand the other. Matches the format of menuInstanceKey.
   const expansionKey = menuInstanceKey;
   const isExpanded = hasSessionSearchQuery ? true : expandedParents.has(expansionKey);
+  const questionBadgeSessionScopes = React.useMemo(
+    () => selectQuestionBadgeSessionScopes(node, isExpanded, sessionDirectory),
+    [isExpanded, node, sessionDirectory],
+  );
+  const pendingQuestionCount = useSessionQuestionCount(questionBadgeSessionScopes);
   const isSubtaskSession = Boolean((resolvedSession as Session & { parentID?: string | null }).parentID);
   const unseenCount = useSessionUnseenCount(session.id);
   const needsAttention = unseenCount > 0 && (!isSubtaskSession || notifyOnSubtasks);
@@ -676,6 +681,9 @@ function SessionNodeItemComponent(props: Props): React.ReactNode {
   }
 
   const pendingPermissionCount = sessionPermissions.length;
+  const pendingQuestionLabel = pendingQuestionCount === 1
+    ? t('sessions.sidebar.session.status.questionPendingSingle')
+    : t('sessions.sidebar.session.status.questionPendingMany', { count: pendingQuestionCount });
   const showUnreadStatus = !isMovingToWorktree && !isStreaming && needsAttention && !isActive;
   const showStatusMarker = isStreaming || showUnreadStatus;
   // Both states are the same static dot; only the color separates "running"
@@ -1292,6 +1300,12 @@ function SessionNodeItemComponent(props: Props): React.ReactNode {
                           <span className="leading-none">{pendingPermissionCount}</span>
                         </span>
                       ) : null}
+                      {pendingQuestionCount > 0 ? (
+                        <span className="inline-flex items-center gap-1 rounded bg-status-info/10 px-1 py-0.5 text-[0.7rem] text-status-info flex-shrink-0" title={pendingQuestionLabel} aria-label={pendingQuestionLabel}>
+                          <Icon name="question" className="h-3 w-3" />
+                          <span className="leading-none">{pendingQuestionCount}</span>
+                        </span>
+                      ) : null}
                     </div>
                   </button>
                 </TooltipTrigger>
diff --git a/packages/ui/src/components/session/sidebar/sessionNodeItemUtils.test.ts b/packages/ui/src/components/session/sidebar/sessionNodeItemUtils.test.ts
index 873796bb..fe43a537 100644
--- a/packages/ui/src/components/session/sidebar/sessionNodeItemUtils.test.ts
+++ b/packages/ui/src/components/session/sidebar/sessionNodeItemUtils.test.ts
@@ -2,7 +2,7 @@ import { describe, expect, test } from 'bun:test';
 import type { Session } from '@opencode-ai/sdk/v2';
 import { getRuntimeKey } from '@/lib/runtime-switch';
 import { getPinnedSessionKey } from '@/stores/useSessionPinnedStore';
-import { computeNodeStructureKey, nodeHasPinnedMembershipChange, selectFolderRootNodes } from './sessionNodeItemUtils';
+import { computeNodeStructureKey, nodeHasPinnedMembershipChange, selectFolderRootNodes, selectQuestionBadgeSessionScopes } from './sessionNodeItemUtils';
 import type { SessionNode } from './types';
 
 const session = (id: string, title: string): Session => ({
@@ -32,6 +32,41 @@ describe('computeNodeStructureKey', () => {
   });
 });
 
+describe('selectQuestionBadgeSessionScopes', () => {
+  const withDirectory = (node: SessionNode, directory: string | null): SessionNode => ({
+    ...node,
+    session: { ...node.session, directory } as Session,
+  });
+
+  test('rolls up the hidden subtree by owning directory when a parent is collapsed', () => {
+    const grandchild = withDirectory({ session: session('grandchild', 'Grandchild'), children: [], worktree: null }, '/worktrees/feature');
+    const child = withDirectory({ session: session('child', 'Child'), children: [grandchild], worktree: null }, '/worktrees/feature');
+    const root = withDirectory({ session: session('root', 'Root'), children: [child], worktree: null }, '/repo');
+
+    expect(selectQuestionBadgeSessionScopes(root, false, '/repo')).toEqual([
+      { directory: '/repo', sessionIDs: ['root'] },
+      { directory: '/worktrees/feature', sessionIDs: ['child', 'grandchild'] },
+    ]);
+  });
+
+  test('keeps expanded rows accurate to their own session only', () => {
+    const child = withDirectory({ session: session('child', 'Child'), children: [], worktree: null }, '/worktrees/feature');
+    const root = withDirectory({ session: session('root', 'Root'), children: [child], worktree: null }, '/repo');
+
+    expect(selectQuestionBadgeSessionScopes(root, true, '/repo')).toEqual([
+      { directory: '/repo', sessionIDs: ['root'] },
+    ]);
+  });
+
+  test('falls back to the group directory when the session has none', () => {
+    const root: SessionNode = { session: session('root', 'Root'), children: [], worktree: null };
+
+    expect(selectQuestionBadgeSessionScopes(root, false, '/fallback')).toEqual([
+      { directory: '/fallback', sessionIDs: ['root'] },
+    ]);
+  });
+});
+
 describe('nodeHasPinnedMembershipChange', () => {
   test('detects composite pin changes using the group directory fallback', () => {
     const node: SessionNode = {
diff --git a/packages/ui/src/components/session/sidebar/sessionNodeItemUtils.ts b/packages/ui/src/components/session/sidebar/sessionNodeItemUtils.ts
index 8bb67ce2..3de83638 100644
--- a/packages/ui/src/components/session/sidebar/sessionNodeItemUtils.ts
+++ b/packages/ui/src/components/session/sidebar/sessionNodeItemUtils.ts
@@ -1,4 +1,6 @@
 import { getRuntimeKey } from '@/lib/runtime-switch';
+import { normalizePath } from '@/lib/pathNormalization';
+import { resolveGlobalSessionDirectory } from '@/stores/useGlobalSessionsStore';
 import { getPinnedSessionKey } from '@/stores/useSessionPinnedStore';
 import type { SessionNode } from './types';
 
@@ -70,6 +72,41 @@ export const nodeContainsSessionId = (node: SessionNode, sessionId: string | nul
   return false;
 };
 
+export type QuestionBadgeSessionScope = {
+  directory: string;
+  sessionIDs: string[];
+};
+
+/**
+ * Choose which (directory, sessionIDs) scopes a sidebar row's pending-question
+ * badge should count. An expanded row counts only its own session; a collapsed
+ * parent row additionally rolls up the hidden descendants of its subtree,
+ * grouped by the directory store each descendant actually lives in, so badges
+ * stay correct for worktree/subtask sessions without bootstrapping their
+ * directory stores.
+ */
+export const selectQuestionBadgeSessionScopes = (
+  node: SessionNode,
+  isExpanded: boolean,
+  fallbackDirectory: string | null,
+): QuestionBadgeSessionScope[] => {
+  const sessionIDsByDirectory = new Map<string, string[]>();
+  const visit = (current: SessionNode): void => {
+    const directory = resolveGlobalSessionDirectory(current.session)
+      ?? normalizePath(current.worktree?.path)
+      ?? fallbackDirectory;
+    if (directory) {
+      const sessionIDs = sessionIDsByDirectory.get(directory) ?? [];
+      sessionIDs.push(current.session.id);
+      sessionIDsByDirectory.set(directory, sessionIDs);
+    }
+    if (current === node && isExpanded) return;
+    for (const child of current.children) visit(child);
+  };
+  visit(node);
+  return [...sessionIDsByDirectory].map(([directory, sessionIDs]) => ({ directory, sessionIDs }));
+};
+
 export const selectFolderRootNodes = (
   sessionIds: string[],
   nodeBySessionId: ReadonlyMap<string, SessionNode>,
diff --git a/packages/ui/src/lib/i18n/messages/de.ts b/packages/ui/src/lib/i18n/messages/de.ts
index 57a22de2..b4c3457e 100644
--- a/packages/ui/src/lib/i18n/messages/de.ts
+++ b/packages/ui/src/lib/i18n/messages/de.ts
@@ -473,6 +473,8 @@ export const dict = {
   'sessions.sidebar.session.status.unread': 'Ungelesene Updates',
   'sessions.sidebar.session.status.pinned': 'Angeheftete Sitzung',
   'sessions.sidebar.session.status.permissionRequired': 'Berechtigung erforderlich',
+  'sessions.sidebar.session.status.questionPendingSingle': '1 ausstehende Frage',
+  'sessions.sidebar.session.status.questionPendingMany': '{count} ausstehende Fragen',
   'sessions.sidebar.session.status.activeFor': 'Seit {duration} aktiv',
   'sessions.sidebar.session.status.lastTurnDuration': 'Letzter Durchlauf dauerte {duration}',
   'sessions.sidebar.session.subsessions.collapse': 'Untersitzungen einklappen',
diff --git a/packages/ui/src/lib/i18n/messages/en.ts b/packages/ui/src/lib/i18n/messages/en.ts
index c77d6a07..abc035b4 100644
--- a/packages/ui/src/lib/i18n/messages/en.ts
+++ b/packages/ui/src/lib/i18n/messages/en.ts
@@ -530,6 +530,8 @@ export const dict = {
   'sessions.sidebar.session.status.pinned': 'Pinned session',
   'sessions.sidebar.session.status.movingToWorktree': 'Moving session to a new worktree',
   'sessions.sidebar.session.status.permissionRequired': 'Permission required',
+  'sessions.sidebar.session.status.questionPendingSingle': '1 pending question',
+  'sessions.sidebar.session.status.questionPendingMany': '{count} pending questions',
   'sessions.sidebar.session.status.activeFor': 'Active for {duration}',
   'sessions.sidebar.session.status.lastTurnDuration': 'Last turn took {duration}',
   'sessions.sidebar.session.subsessions.collapse': 'Collapse subsessions',
diff --git a/packages/ui/src/lib/i18n/messages/es.ts b/packages/ui/src/lib/i18n/messages/es.ts
index 72985914..8b1cb42f 100644
--- a/packages/ui/src/lib/i18n/messages/es.ts
+++ b/packages/ui/src/lib/i18n/messages/es.ts
@@ -531,6 +531,8 @@ export const dict: Record<I18nKey, string> = {
   "sessions.sidebar.session.status.pinned": "Sesión anclada",
   "sessions.sidebar.session.status.movingToWorktree": "Moviendo la sesión a un worktree nuevo",
   "sessions.sidebar.session.status.permissionRequired": "Permiso requerido",
+  "sessions.sidebar.session.status.questionPendingSingle": "1 pregunta pendiente",
+  "sessions.sidebar.session.status.questionPendingMany": "{count} preguntas pendientes",
   "sessions.sidebar.session.status.activeFor": "Activa desde hace {duration}",
   "sessions.sidebar.session.status.lastTurnDuration": "El último turno duró {duration}",
   "sessions.sidebar.session.subsessions.collapse": "Colapsar subsesiones",
diff --git a/packages/ui/src/lib/i18n/messages/fr.ts b/packages/ui/src/lib/i18n/messages/fr.ts
index 986a4cd4..d34fead6 100644
--- a/packages/ui/src/lib/i18n/messages/fr.ts
+++ b/packages/ui/src/lib/i18n/messages/fr.ts
@@ -366,6 +366,8 @@ export const dict = {
   'sessions.sidebar.session.status.pinned': 'Session épinglée',
   'sessions.sidebar.session.status.movingToWorktree': 'Déplacement de la session vers un nouveau worktree',
   'sessions.sidebar.session.status.permissionRequired': 'Autorisation requise',
+  'sessions.sidebar.session.status.questionPendingSingle': '1 question en attente',
+  'sessions.sidebar.session.status.questionPendingMany': '{count} questions en attente',
   'sessions.sidebar.session.status.activeFor': 'Active depuis {duration}',
   'sessions.sidebar.session.status.lastTurnDuration': 'Le dernier tour a duré {duration}',
   'sessions.sidebar.session.subsessions.collapse': 'Réduire les sous-sessions',
diff --git a/packages/ui/src/lib/i18n/messages/ja.ts b/packages/ui/src/lib/i18n/messages/ja.ts
index 0f4da4e7..58b1503c 100644
--- a/packages/ui/src/lib/i18n/messages/ja.ts
+++ b/packages/ui/src/lib/i18n/messages/ja.ts
@@ -531,6 +531,8 @@ export const dict: Record<I18nKey, string> = {
   'sessions.sidebar.session.status.pinned': 'ピン留めされたセッション',
   'sessions.sidebar.session.status.movingToWorktree': 'セッションを新しいworktreeへ移動中',
   'sessions.sidebar.session.status.permissionRequired': '権限が必要です',
+  'sessions.sidebar.session.status.questionPendingSingle': '保留中の質問が1件あります',
+  'sessions.sidebar.session.status.questionPendingMany': '保留中の質問が{count}件あります',
   'sessions.sidebar.session.status.activeFor': 'アクティブ時間 {duration}',
   'sessions.sidebar.session.status.lastTurnDuration': '前回のターンの所要時間 {duration}',
   'sessions.sidebar.session.subsessions.collapse': 'サブセッションを折りたたむ',
diff --git a/packages/ui/src/lib/i18n/messages/ko.ts b/packages/ui/src/lib/i18n/messages/ko.ts
index 0f09fba2..5fa4c718 100644
--- a/packages/ui/src/lib/i18n/messages/ko.ts
+++ b/packages/ui/src/lib/i18n/messages/ko.ts
@@ -531,6 +531,8 @@ export const dict: Record<I18nKey, string> = {
   'sessions.sidebar.session.status.pinned': '고정된 세션',
   'sessions.sidebar.session.status.movingToWorktree': '세션을 새 worktree로 이동하는 중',
   'sessions.sidebar.session.status.permissionRequired': '권한 필요',
+  'sessions.sidebar.session.status.questionPendingSingle': '대기 중인 질문 1개',
+  'sessions.sidebar.session.status.questionPendingMany': '대기 중인 질문 {count}개',
   'sessions.sidebar.session.status.activeFor': '{duration} 동안 활성 상태',
   'sessions.sidebar.session.status.lastTurnDuration': '마지막 턴 소요 시간 {duration}',
   'sessions.sidebar.session.subsessions.collapse': '하위 세션 접기',
diff --git a/packages/ui/src/lib/i18n/messages/pl.ts b/packages/ui/src/lib/i18n/messages/pl.ts
index 12f727b1..41bceff7 100644
--- a/packages/ui/src/lib/i18n/messages/pl.ts
+++ b/packages/ui/src/lib/i18n/messages/pl.ts
@@ -531,6 +531,8 @@ export const dict: Record<I18nKey, string> = {
   'sessions.sidebar.session.status.pinned': 'Przypięta sesja',
   'sessions.sidebar.session.status.movingToWorktree': 'Przenoszenie sesji do nowego worktree',
   'sessions.sidebar.session.status.permissionRequired': 'Wymagane uprawnienie',
+  'sessions.sidebar.session.status.questionPendingSingle': '1 oczekujące pytanie',
+  'sessions.sidebar.session.status.questionPendingMany': 'Liczba oczekujących pytań: {count}',
   'sessions.sidebar.session.status.activeFor': 'Aktywna od {duration}',
   'sessions.sidebar.session.status.lastTurnDuration': 'Ostatnia tura trwała {duration}',
   'sessions.sidebar.session.subsessions.collapse': 'Zwiń pod-sesje',
diff --git a/packages/ui/src/lib/i18n/messages/pt-BR.ts b/packages/ui/src/lib/i18n/messages/pt-BR.ts
index 10dd7709..76af1d1e 100644
--- a/packages/ui/src/lib/i18n/messages/pt-BR.ts
+++ b/packages/ui/src/lib/i18n/messages/pt-BR.ts
@@ -531,6 +531,8 @@ export const dict: Record<I18nKey, string> = {
   "sessions.sidebar.session.status.pinned": "Sessão fixada",
   "sessions.sidebar.session.status.movingToWorktree": "Movendo a sessão para um novo worktree",
   "sessions.sidebar.session.status.permissionRequired": "Permissão obrigatória",
+  "sessions.sidebar.session.status.questionPendingSingle": "1 pergunta pendente",
+  "sessions.sidebar.session.status.questionPendingMany": "{count} perguntas pendentes",
   "sessions.sidebar.session.status.activeFor": "Ativa há {duration}",
   "sessions.sidebar.session.status.lastTurnDuration": "O último turno levou {duration}",
   "sessions.sidebar.session.subsessions.collapse": "Recolher subsessões",
diff --git a/packages/ui/src/lib/i18n/messages/uk.ts b/packages/ui/src/lib/i18n/messages/uk.ts
index dd52bcb9..90df90e9 100644
--- a/packages/ui/src/lib/i18n/messages/uk.ts
+++ b/packages/ui/src/lib/i18n/messages/uk.ts
@@ -531,6 +531,8 @@ export const dict: Record<I18nKey, string> = {
   "sessions.sidebar.session.status.pinned": "Закріплений сесія",
   "sessions.sidebar.session.status.movingToWorktree": "Перенесення сесії в новий worktree",
   "sessions.sidebar.session.status.permissionRequired": "Потрібен дозвіл",
+  "sessions.sidebar.session.status.questionPendingSingle": "1 запитання очікує відповіді",
+  "sessions.sidebar.session.status.questionPendingMany": "Кількість запитань, що очікують відповіді: {count}",
   "sessions.sidebar.session.status.activeFor": "Активна вже {duration}",
   "sessions.sidebar.session.status.lastTurnDuration": "Останній хід тривав {duration}",
   "sessions.sidebar.session.subsessions.collapse": "Згорнути підсесії",
diff --git a/packages/ui/src/lib/i18n/messages/zh-CN.ts b/packages/ui/src/lib/i18n/messages/zh-CN.ts
index 35de2c9c..e6f11141 100644
--- a/packages/ui/src/lib/i18n/messages/zh-CN.ts
+++ b/packages/ui/src/lib/i18n/messages/zh-CN.ts
@@ -531,6 +531,8 @@ export const dict: Record<I18nKey, string> = {
   'sessions.sidebar.session.status.pinned': '已置顶会话',
   'sessions.sidebar.session.status.movingToWorktree': '正在将会话移至新工作树',
   'sessions.sidebar.session.status.permissionRequired': '需要权限',
+  'sessions.sidebar.session.status.questionPendingSingle': '1 个待回答问题',
+  'sessions.sidebar.session.status.questionPendingMany': '{count} 个待回答问题',
   'sessions.sidebar.session.status.activeFor': '已活动 {duration}',
   'sessions.sidebar.session.status.lastTurnDuration': '上一轮耗时 {duration}',
   'sessions.sidebar.session.subsessions.collapse': '折叠子会话',
diff --git a/packages/ui/src/lib/i18n/messages/zh-TW.ts b/packages/ui/src/lib/i18n/messages/zh-TW.ts
index 6641606b..d71368c7 100644
--- a/packages/ui/src/lib/i18n/messages/zh-TW.ts
+++ b/packages/ui/src/lib/i18n/messages/zh-TW.ts
@@ -544,6 +544,8 @@ export const dict: Record<I18nKey, string> = {
   'sessions.sidebar.session.status.pinned': '已釘選會話',
   'sessions.sidebar.session.status.movingToWorktree': '正在將會話移至新工作樹',
   'sessions.sidebar.session.status.permissionRequired': '需要權限',
+  'sessions.sidebar.session.status.questionPendingSingle': '1 個待回答問題',
+  'sessions.sidebar.session.status.questionPendingMany': '{count} 個待回答問題',
   'sessions.sidebar.session.status.activeFor': '已活動 {duration}',
   'sessions.sidebar.session.status.lastTurnDuration': '上一輪耗時 {duration}',
   'sessions.sidebar.session.subsessions.collapse': '摺疊子會話',
diff --git a/packages/ui/src/sync/DOCUMENTATION.md b/packages/ui/src/sync/DOCUMENTATION.md
index 5699fc93..13e4f5d7 100644
--- a/packages/ui/src/sync/DOCUMENTATION.md
+++ b/packages/ui/src/sync/DOCUMENTATION.md
@@ -204,7 +204,7 @@ Incomplete-session materialization is deduplicated by runtime, directory, and se
 
 When `session.idle` or `session.error` settles a session but the trailing assistant message still contains a `pending` or `running` tool, sync refreshes that session tail. This narrowly reconciles a missed terminal tool-part event without refetching normally completed turns or stale tools from older turns. A stale refresh or delayed part event cannot regress a locally observed terminal tool to an active status.
 
-Directory stores also own session-keyed sidecar notification channels for permissions and message materialization. High-frequency realtime part events annotate the exact session/message before committing, so visible records, user history, renderability, and sidebar permission rows are not notified by unrelated sessions. Structural message replacements notify only changed subscribed session buckets; unannotated bulk part replacement conservatively resets active message subscribers so bootstrap, pagination, rollback, and legacy writers cannot leave stale projections.
+Directory stores also own session-keyed sidecar notification channels for permissions, questions, and message materialization. High-frequency realtime part events annotate the exact session/message before committing, so visible records, user history, renderability, and sidebar permission and question rows are not notified by unrelated sessions. Structural message replacements notify only changed subscribed session buckets; unannotated bulk part replacement conservatively resets active message subscribers so bootstrap, pagination, rollback, and legacy writers cannot leave stale projections.
 
 Message sidecar consumers also filter targeted updates by purpose before notifying React. Suspended live-tail text/reasoning changes do not rebuild visible message records, but structural Task session identity changes bypass suspension so a parent can link a newly created subagent immediately. Assistant-only part changes do not rebuild user input history, and targeted updates that preserve authoritative part buckets do not recheck a session that is already renderable. Message replacements, removed final part buckets, and conservative resets always notify.
 
@@ -345,7 +345,7 @@ Keep this in sync with `handleDirectoryEvent` in `sync-context.tsx`:
 
 | Event type | Fields to clone |
 |---|---|
-| `session.created/updated/deleted` | `session`, `permission`, `todo`, `part` |
+| `session.created/updated/deleted` | `session`, `permission`, `todo`, `part`; archived/deleted sessions also clone `question` |
 | `session.diff` | `session_diff` |
 | `session.status` | `session_status` |
 | `todo.updated` | `todo` |
diff --git a/packages/ui/src/sync/child-store.test.ts b/packages/ui/src/sync/child-store.test.ts
index 1ec3b0dc..64fed08f 100644
--- a/packages/ui/src/sync/child-store.test.ts
+++ b/packages/ui/src/sync/child-store.test.ts
@@ -4,6 +4,8 @@ import {
   ChildStoreManager,
   markDirectorySessionPartChanged,
   subscribeDirectoryPermission,
+  subscribeDirectoryQuestion,
+  subscribeDirectoryQuestions,
   subscribeDirectorySessionMessages,
 } from './child-store';
 import {
@@ -120,6 +122,132 @@ describe('ChildStoreManager permission subscriptions', () => {
   });
 });
 
+describe('ChildStoreManager question subscriptions', () => {
+  test('notifies only the owning session and ignores unrelated high-frequency updates', () => {
+    const manager = new ChildStoreManager();
+    const child = manager.ensureChild('/workspace', { bootstrap: false });
+    const notifications = new Map<string, number>();
+    const unsubscribers = Array.from({ length: 50 }, (_, index) => {
+      const sessionID = `session-${index}`;
+      return subscribeDirectoryQuestion(child, sessionID, () => {
+        notifications.set(sessionID, (notifications.get(sessionID) ?? 0) + 1);
+      });
+    });
+    setSyncPerformanceDiagnosticsEnabled(true);
+
+    for (let index = 0; index < 10_000; index += 1) {
+      child.setState({ part: { [`message-${index}`]: [] } });
+    }
+
+    expect(notifications.size).toBe(0);
+    expect(getSyncPerformanceDiagnostics()?.questionChangeCallbacks).toBe(0);
+
+    child.setState({ question: { 'session-17': [{ id: 'question-1' }] as never[] } });
+
+    expect(notifications.get('session-17')).toBe(1);
+    expect(notifications.size).toBe(1);
+    expect(getSyncPerformanceDiagnostics()?.questionChangeCallbacks).toBe(1);
+
+    // A new map that preserves session-17's bucket must not notify it again.
+    child.setState({ question: { ...child.getState().question, 'session-18': [{ id: 'question-2' }] as never[] } });
+
+    expect(notifications.get('session-17')).toBe(1);
+    expect(notifications.get('session-18')).toBe(1);
+    expect(getSyncPerformanceDiagnostics()?.questionChangeCallbacks).toBe(2);
+
+    child.setState({ question: {} });
+
+    expect(notifications.get('session-17')).toBe(2);
+    expect(notifications.get('session-18')).toBe(2);
+    expect(getSyncPerformanceDiagnostics()?.questionChangeCallbacks).toBe(4);
+
+    for (const unsubscribe of unsubscribers) unsubscribe();
+    setSyncPerformanceDiagnosticsEnabled(false);
+    manager.disposeAll();
+  });
+
+  test('notifies subtree and exact-session rows once for each relevant replacement', () => {
+    const manager = new ChildStoreManager();
+    const child = manager.ensureChild('/workspace', { bootstrap: false });
+    let parentNotifications = 0;
+    let childNotifications = 0;
+    const unsubscribeParent = subscribeDirectoryQuestions(child, ['parent', 'child'], () => {
+      parentNotifications += 1;
+    });
+    const unsubscribeChild = subscribeDirectoryQuestion(child, 'child', () => {
+      childNotifications += 1;
+    });
+    const parentQuestions = [{ id: 'question-parent' }] as never[];
+    const childQuestions = [{ id: 'question-child' }] as never[];
+
+    child.setState({ question: { parent: parentQuestions, child: childQuestions } });
+
+    expect(parentNotifications).toBe(1);
+    expect(childNotifications).toBe(1);
+
+    child.setState({ part: { message: [] } });
+    expect(parentNotifications).toBe(1);
+    expect(childNotifications).toBe(1);
+
+    child.setState({
+      question: {
+        parent: parentQuestions,
+        child: [{ id: 'question-child-replacement' }] as never[],
+      },
+    });
+
+    expect(parentNotifications).toBe(2);
+    expect(childNotifications).toBe(2);
+
+    child.setState({ question: {} });
+
+    expect(parentNotifications).toBe(3);
+    expect(childNotifications).toBe(3);
+
+    unsubscribeParent();
+    unsubscribeChild();
+    manager.disposeAll();
+  });
+
+  test('aggregates exact question buckets across directory stores', () => {
+    const manager = new ChildStoreManager();
+    const parentStore = manager.ensureChild('/repo', { bootstrap: false });
+    const childStore = manager.ensureChild('/worktrees/feature', { bootstrap: false });
+    let notifications = 0;
+    const notify = () => {
+      notifications += 1;
+    };
+    const unsubscribers = [
+      subscribeDirectoryQuestions(parentStore, ['parent'], notify),
+      subscribeDirectoryQuestions(childStore, ['child'], notify),
+    ];
+    const questionCount = () => (
+      (parentStore.getState().question.parent?.length ?? 0)
+      + (childStore.getState().question.child?.length ?? 0)
+    );
+
+    childStore.setState({ question: { child: [{ id: 'child-question' }] as never[] } });
+    expect(questionCount()).toBe(1);
+    expect(notifications).toBe(1);
+
+    childStore.setState({
+      question: {
+        ...childStore.getState().question,
+        unrelated: [{ id: 'unrelated-question' }] as never[],
+      },
+    });
+    expect(questionCount()).toBe(1);
+    expect(notifications).toBe(1);
+
+    parentStore.setState({ question: { parent: [{ id: 'parent-question' }] as never[] } });
+    expect(questionCount()).toBe(2);
+    expect(notifications).toBe(2);
+
+    for (const unsubscribe of unsubscribers) unsubscribe();
+    manager.disposeAll();
+  });
+});
+
 describe('ChildStoreManager session message subscriptions', () => {
   test('routes annotated part changes only to the owning session', () => {
     const manager = new ChildStoreManager();
diff --git a/packages/ui/src/sync/child-store.ts b/packages/ui/src/sync/child-store.ts
index 0b0142de..f3b5b194 100644
--- a/packages/ui/src/sync/child-store.ts
+++ b/packages/ui/src/sync/child-store.ts
@@ -14,8 +14,10 @@ export type DirectoryStore = State & {
   replace: (next: State) => void
 }
 
-type PermissionSubscriber = () => void
-const permissionSubscribersByStore = new WeakMap<StoreApi<DirectoryStore>, Map<string, Set<PermissionSubscriber>>>()
+type BlockingRequestSubscriber = () => void
+type BlockingRequestSubscribers = WeakMap<StoreApi<DirectoryStore>, Map<string, Set<BlockingRequestSubscriber>>>
+const permissionSubscribersByStore: BlockingRequestSubscribers = new WeakMap()
+const questionSubscribersByStore: BlockingRequestSubscribers = new WeakMap()
 
 type SessionMessageChange = {
   messagesChanged: boolean
@@ -72,12 +74,42 @@ export function markDirectorySessionPartChanged(
 export function subscribeDirectoryPermission(
   store: StoreApi<DirectoryStore>,
   sessionID: string,
-  listener: PermissionSubscriber,
+  listener: BlockingRequestSubscriber,
 ): () => void {
-  let bySession = permissionSubscribersByStore.get(store)
+  return subscribeBlockingRequest(permissionSubscribersByStore, store, sessionID, listener)
+}
+
+export function subscribeDirectoryQuestion(
+  store: StoreApi<DirectoryStore>,
+  sessionID: string,
+  listener: BlockingRequestSubscriber,
+): () => void {
+  return subscribeBlockingRequest(questionSubscribersByStore, store, sessionID, listener)
+}
+
+export function subscribeDirectoryQuestions(
+  store: StoreApi<DirectoryStore>,
+  sessionIDs: readonly string[],
+  listener: BlockingRequestSubscriber,
+): () => void {
+  const unsubscribers = [...new Set(sessionIDs.filter(Boolean))].map((sessionID) => (
+    subscribeBlockingRequest(questionSubscribersByStore, store, sessionID, listener)
+  ))
+  return () => {
+    for (const unsubscribe of unsubscribers) unsubscribe()
+  }
+}
+
+function subscribeBlockingRequest(
+  subscribersByStore: BlockingRequestSubscribers,
+  store: StoreApi<DirectoryStore>,
+  sessionID: string,
+  listener: BlockingRequestSubscriber,
+): () => void {
+  let bySession = subscribersByStore.get(store)
   if (!bySession) {
     bySession = new Map()
-    permissionSubscribersByStore.set(store, bySession)
+    subscribersByStore.set(store, bySession)
   }
   let listeners = bySession.get(sessionID)
   if (!listeners) {
@@ -88,24 +120,28 @@ export function subscribeDirectoryPermission(
   return () => {
     listeners?.delete(listener)
     if (listeners?.size === 0) bySession?.delete(sessionID)
-    if (bySession?.size === 0) permissionSubscribersByStore.delete(store)
+    if (bySession?.size === 0) subscribersByStore.delete(store)
   }
 }
 
-const notifyChangedPermissions = (
+const notifyChangedBlockingRequests = <T,>(
+  subscribersByStore: BlockingRequestSubscribers,
+  counter: "permissionChangeCallbacks" | "questionChangeCallbacks",
   store: StoreApi<DirectoryStore>,
-  current: State["permission"],
-  previous: State["permission"],
+  current: Record<string, T>,
+  previous: Record<string, T>,
 ): void => {
   if (current === previous) return
-  const subscribers = permissionSubscribersByStore.get(store)
+  const subscribers = subscribersByStore.get(store)
   if (!subscribers || subscribers.size === 0) return
+  const changedListeners = new Set<BlockingRequestSubscriber>()
   for (const [sessionID, listeners] of subscribers) {
     if (current[sessionID] === previous[sessionID]) continue
-    for (const listener of listeners) {
-      countSyncPerformance("permissionChangeCallbacks")
-      listener()
-    }
+    for (const listener of listeners) changedListeners.add(listener)
+  }
+  for (const listener of changedListeners) {
+    countSyncPerformance(counter)
+    listener()
   }
 }
 
@@ -239,7 +275,8 @@ function createDirectoryStore(directory: string): StoreApi<DirectoryStore> {
     if (state.projectMeta !== prev.projectMeta) persistProjectMeta(directory, state.projectMeta)
     if (state.icon !== prev.icon) persistIcon(directory, state.icon)
     if (state.session !== prev.session) persistSessions(directory, state.session)
-    notifyChangedPermissions(store, state.permission, prev.permission)
+    notifyChangedBlockingRequests(permissionSubscribersByStore, "permissionChangeCallbacks", store, state.permission, prev.permission)
+    notifyChangedBlockingRequests(questionSubscribersByStore, "questionChangeCallbacks", store, state.question, prev.question)
     notifyChangedSessionMessages(store, state, prev)
   })
 
diff --git a/packages/ui/src/sync/performance-diagnostics.ts b/packages/ui/src/sync/performance-diagnostics.ts
index 063e4697..c7f41823 100644
--- a/packages/ui/src/sync/performance-diagnostics.ts
+++ b/packages/ui/src/sync/performance-diagnostics.ts
@@ -24,6 +24,7 @@ export type SyncPerformanceCounters = {
   streamingHeartbeatAttempts: number
   streamingHeartbeatCommits: number
   permissionChangeCallbacks: number
+  questionChangeCallbacks: number
   sessionMessageChangeCallbacks: number
   sessionRenderableNotificationSkips: number
   userMessageHistoryNotificationSkips: number
@@ -57,6 +58,7 @@ const createCounters = (): SyncPerformanceCounters => ({
   streamingHeartbeatAttempts: 0,
   streamingHeartbeatCommits: 0,
   permissionChangeCallbacks: 0,
+  questionChangeCallbacks: 0,
   sessionMessageChangeCallbacks: 0,
   sessionRenderableNotificationSkips: 0,
   userMessageHistoryNotificationSkips: 0,
diff --git a/packages/ui/src/sync/sync-context.tsx b/packages/ui/src/sync/sync-context.tsx
index b4ff6c19..99e6624b 100644
--- a/packages/ui/src/sync/sync-context.tsx
+++ b/packages/ui/src/sync/sync-context.tsx
@@ -14,6 +14,7 @@ import {
   ChildStoreManager,
   markDirectorySessionPartChanged,
   subscribeDirectoryPermission,
+  subscribeDirectoryQuestions,
   subscribeDirectorySessionMessages,
   type DirectoryBootstrapContext,
   type DirectoryBootstrapReason,
@@ -1620,6 +1621,12 @@ function handleEvent(
     case "session.deleted":
       cloneField("session", (value) => [...value])
       cloneField("permission", (value) => ({ ...value }))
+      if (
+        payload.type === "session.deleted"
+        || (payload.type === "session.updated" && Boolean((payload.properties as { info?: Session }).info?.time.archived))
+      ) {
+        cloneField("question", (value) => ({ ...value }))
+      }
       cloneField("todo", (value) => ({ ...value }))
       cloneField("part", (value) => ({ ...value }))
       cloneField("sessionEventRevision", (value) => ({ ...(value ?? {}) }))
@@ -2436,6 +2443,46 @@ export function useSessionQuestions(sessionID: string, directory?: string) {
   )
 }
 
+/**
+ * Total number of pending questions across the given session scopes. Each
+ * scope names a directory store plus the session IDs to count inside it, so
+ * collapsed subtree rows can roll up pending questions of hidden descendants
+ * from their owning directory stores without bootstrapping them.
+ *
+ * Subscribes through the per-session question sidecar channel, so unrelated
+ * streaming or session activity does not re-render rows.
+ */
+export function useSessionQuestionCount(scopes: readonly { directory: string; sessionIDs: readonly string[] }[]) {
+  const { childStores } = useSyncSystem()
+  const scopedStores = React.useMemo(() => scopes.map((scope) => ({
+    sessionIDs: scope.sessionIDs,
+    store: childStores.ensureChild(scope.directory, { bootstrap: false }),
+  })), [childStores, scopes])
+  React.useEffect(() => {
+    for (const scope of scopes) childStores.pin(scope.directory)
+    return () => {
+      for (const scope of scopes) childStores.unpin(scope.directory)
+    }
+  }, [childStores, scopes])
+  const getSnapshot = React.useCallback(() => {
+    let count = 0
+    for (const { sessionIDs, store } of scopedStores) {
+      const questions = store.getState().question
+      for (const sessionID of sessionIDs) count += questions[sessionID]?.length ?? 0
+    }
+    return count
+  }, [scopedStores])
+  const subscribe = React.useCallback((notify: () => void) => {
+    const unsubscribers = scopedStores.map(({ sessionIDs, store }) => (
+      subscribeDirectoryQuestions(store, sessionIDs, notify)
+    ))
+    return () => {
+      for (const unsubscribe of unsubscribers) unsubscribe()
+    }
+  }, [scopedStores])
+  return React.useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+}
+
 /** Get sessions list for a directory */
 export function useSessions(directory?: string) {
   return useDirectorySync(

From 7ff86a3bc75ab71127ce08f5a70bc95f605ad66d Mon Sep 17 00:00:00 2001
From: Serhii Dziupin <serkraser@gmail.com>
Date: Wed, 5 Aug 2026 13:44:36 +0300
Subject: [PATCH 24/57] fix(composer): restore Shift+Enter newline on iOS

CodeMirror defers Enter on iOS (and Chrome Android): the real keydown is
captured without running the keymaps and the keymaps then run against a
synthetic keydown that dispatchKey builds from the key name alone, with
no modifier keys. The composer's Shift+Enter thus arrived as a plain
Enter, and on devices where Enter sends (iPad Safari/PWA, where the
desktop layout applies) it submitted the message instead of inserting a
newline.

Record the real Enter keydown's shift state on the view's contentDOM and
restore it onto the deferred synthetic event before the caller's
onKeyDown policy runs, so Shift+Enter means newline again on every
runtime. Plain Enter behavior is untouched: on iOS it still follows the
same deferred path it used before this change.

Fixes #2558
---
 .../chat/composer/editor/ComposerEditor.tsx   | 47 ++++++++++++++++++-
 1 file changed, 46 insertions(+), 1 deletion(-)

diff --git a/packages/ui/src/components/chat/composer/editor/ComposerEditor.tsx b/packages/ui/src/components/chat/composer/editor/ComposerEditor.tsx
index f3715dd7..41a2825f 100644
--- a/packages/ui/src/components/chat/composer/editor/ComposerEditor.tsx
+++ b/packages/ui/src/components/chat/composer/editor/ComposerEditor.tsx
@@ -130,6 +130,16 @@ function insertedTextOf(transaction: { changes: { iterChanges: (fn: (fromA: numb
     return inserted;
 }
 
+/**
+ * True for keydown events CodeMirror re-dispatches after deferring the real
+ * one (iOS Enter/Backspace/Delete, Chrome Android Enter): `dispatchKey`
+ * stamps the replacement event with a `synthetic` expando. These events are
+ * built from the key name alone, so they carry no modifier keys.
+ */
+function isDeferredSyntheticEvent(event: KeyboardEvent): boolean {
+    return Boolean((event as unknown as { synthetic?: boolean }).synthetic);
+}
+
 /**
  * Compartments are configuration keys, not per-view state, so one set can serve
  * every editor. They live at module scope because a kept-alive view outlives
@@ -160,6 +170,14 @@ export const ComposerEditor = React.forwardRef<ComposerEditorHandle, ComposerEdi
         const hostRef = React.useRef<HTMLDivElement | null>(null);
         const viewRef = React.useRef<EditorView | null>(null);
 
+        // The real keydown's shift state for the LAST Enter that reached the
+        // editor. CodeMirror defers Enter on iOS (and Chrome Android) and
+        // re-dispatches it as a synthetic keydown built from the key name
+        // alone, dropping every modifier (see `trackRealEnterShift` and the
+        // `interceptKeys` handler below); this ref is what lets the deferred
+        // event still tell Shift+Enter from Enter.
+        const lastRealEnterShiftRef = React.useRef(false);
+
         // Callbacks reach the CodeMirror extensions through a ref: the view is
         // built once and must not be torn down when a handler identity changes,
         // which would drop focus mid-typing. When a view store is supplied the
@@ -200,7 +218,15 @@ export const ComposerEditor = React.forwardRef<ComposerEditorHandle, ComposerEdi
             }
 
             const interceptKeys: KeyBinding[] = [{
-                any: (_view, event) => handlersRef.current.onKeyDown?.(event) ?? false,
+                any: (_view, event) => {
+                    // A deferred Enter lost its modifiers in the re-dispatch;
+                    // give the caller's policy (Enter vs Shift+Enter) back the
+                    // shift state it saw on the real keydown.
+                    if (event.key === 'Enter' && isDeferredSyntheticEvent(event) && lastRealEnterShiftRef.current) {
+                        Object.defineProperty(event, 'shiftKey', { value: true });
+                    }
+                    return handlersRef.current.onKeyDown?.(event) ?? false;
+                },
             }];
 
             const view = new EditorView({
@@ -276,6 +302,25 @@ export const ComposerEditor = React.forwardRef<ComposerEditorHandle, ComposerEdi
             viewRef.current = view;
             if (store) store.view = view;
 
+            // CodeMirror defers Enter on iOS (and Chrome Android): the real
+            // keydown is captured without running the keymaps, the browser's
+            // native newline goes through, and the keymaps then run against a
+            // synthetic keydown `dispatchKey` builds from the key name alone —
+            // which has NO modifiers. Recording the real shift state here (a
+            // plain listener, registered after CodeMirror's own, so it runs
+            // after the deferral decision but before the deferred dispatch)
+            // lets the deferred Enter be re-presented with Shift+Enter intact
+            // instead of arriving as a plain Enter that "sends" where Enter
+            // sends. Without it, Shift+Enter on iOS/Android submits the
+            // message instead of inserting a newline. The listener lives on
+            // the kept-alive view's contentDOM, so it stays across mounts and
+            // keeps feeding the same ref the `interceptKeys` closure reads.
+            const trackRealEnterShift = (event: KeyboardEvent) => {
+                if (event.key !== 'Enter' || isDeferredSyntheticEvent(event)) return;
+                lastRealEnterShiftRef.current = event.shiftKey;
+            };
+            view.contentDOM.addEventListener('keydown', trackRealEnterShift);
+
             return () => {
                 viewRef.current = null;
                 // A stored view is detached, not destroyed: the store owns its

From 13f6a0280d7d4699579c8e272ee7a6ae0de92225 Mon Sep 17 00:00:00 2001
From: Serhii Dziupin <serkraser@gmail.com>
Date: Wed, 5 Aug 2026 13:59:17 +0300
Subject: [PATCH 25/57] fix(server): rebind message-stream upstreams after a
 managed OpenCode restart
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When the managed OpenCode process exits but a server survives on the old
port (Windows: killProcessOnPort is a no-op, so the orphaned process tree
keeps the port), restartOpenCode() times out waiting for the port and
spawns a fresh server on a NEW port. HTTP/proxy traffic follows the new
port, but the global message-stream hub's upstream SSE reader stays pinned
to the old server's /global/event stream — that connection never closes —
so new events never reach the UI and the chat stops updating until the
app is restarted (#2638).

Lifecycle now fires an optional onOpenCodeRestarted hook after a
successful managed restart; index.js wires it to the new
messageStreamRuntime.rebindUpstream(), which restarts the shared hub
(its reader re-dials buildOpenCodeUrl → the current port) and closes
directory-scoped sockets so their per-connection readers rebuild against
the new port. External servers are untouched (their port cannot change).

Fixes #2638
---
 packages/web/server/index.js                  |  13 +
 .../server/lib/event-stream/rebind.test.js    | 186 +++++++++
 .../web/server/lib/event-stream/runtime.js    |  32 ++
 packages/web/server/lib/opencode/lifecycle.js |  12 +
 .../web/server/lib/opencode/lifecycle.test.js |  64 +++
 scripts/repro/issue-2638/README.md            |  47 +++
 .../repro/issue-2638/fake-opencode-serve.mjs  | 151 +++++++
 scripts/repro/issue-2638/reproduce-2638.mjs   | 376 ++++++++++++++++++
 8 files changed, 881 insertions(+)
 create mode 100644 packages/web/server/lib/event-stream/rebind.test.js
 create mode 100644 scripts/repro/issue-2638/README.md
 create mode 100755 scripts/repro/issue-2638/fake-opencode-serve.mjs
 create mode 100644 scripts/repro/issue-2638/reproduce-2638.mjs

diff --git a/packages/web/server/index.js b/packages/web/server/index.js
index 1c386b3c..4eac3336 100644
--- a/packages/web/server/index.js
+++ b/packages/web/server/index.js
@@ -1079,6 +1079,19 @@ const openCodeLifecycleRuntime = createOpenCodeLifecycleRuntime({
     }
     return [...new Set(directories)];
   },
+  // A managed restart can move OpenCode to a NEW port (the old one may stay
+  // occupied by an orphaned process, e.g. killProcessOnPort is a no-op on
+  // Windows). Rebind the message-stream upstream readers to the current port
+  // so the UI keeps receiving events instead of staying pinned to the old
+  // process (#2638). The runtime is created later by the startup pipeline;
+  // by the time any restart runs, it is assigned.
+  onOpenCodeRestarted: () => {
+    try {
+      messageStreamRuntime?.rebindUpstream();
+    } catch (error) {
+      console.warn('Failed to rebind message stream after OpenCode restart:', error?.message ?? error);
+    }
+  },
   getManagedOpenCodeEnv: async () => {
     const settings = await readSettingsFromDiskMigrated().catch(() => null);
     const managedEnv = settings?.agentControlToolEnabled === false
diff --git a/packages/web/server/lib/event-stream/rebind.test.js b/packages/web/server/lib/event-stream/rebind.test.js
new file mode 100644
index 00000000..ebf821f2
--- /dev/null
+++ b/packages/web/server/lib/event-stream/rebind.test.js
@@ -0,0 +1,186 @@
+import { EventEmitter } from 'node:events';
+import { describe, expect, it, vi } from 'vitest';
+
+import { createGlobalMessageStreamHub } from './global-hub.js';
+import { createMessageStreamWsRuntime } from './runtime.js';
+
+class FakeSocket extends EventEmitter {
+  constructor() {
+    super();
+    this.readyState = 1;
+    this.sent = [];
+    this.closeCalls = [];
+  }
+
+  send(payload) {
+    this.sent.push(JSON.parse(payload));
+  }
+
+  ping() {
+    void 0;
+  }
+
+  close(code, reason) {
+    if (this.readyState === 3) {
+      return;
+    }
+    this.readyState = 3;
+    this.closeCalls.push({ code, reason });
+    this.emit('close');
+  }
+}
+
+function createSseResponse({ blocks = [], signal, holdOpen = false }) {
+  const encoder = new TextEncoder();
+  let index = 0;
+
+  return {
+    ok: true,
+    body: {
+      getReader() {
+        return {
+          async read() {
+            if (index < blocks.length) {
+              const next = blocks[index++];
+              return { value: encoder.encode(next), done: false };
+            }
+
+            if (!holdOpen) {
+              return { value: undefined, done: true };
+            }
+
+            return new Promise((resolve, reject) => {
+              const onAbort = () => {
+                signal.removeEventListener('abort', onAbort);
+                const error = new Error('Aborted');
+                error.name = 'AbortError';
+                reject(error);
+              };
+              signal.addEventListener('abort', onAbort, { once: true });
+            });
+          },
+        };
+      },
+    },
+  };
+}
+
+describe('rebindUpstream (#2638)', () => {
+  it('restarts the shared hub upstream so a connected client resumes receiving events on the new port', async () => {
+    const server = new EventEmitter();
+    const wsClients = new Set();
+    let port = 4096;
+    let fetchCalls = 0;
+
+    // Port changes after a managed restart: buildOpenCodeUrl resolves the
+    // CURRENT port on every attempt, exactly like production network-runtime.
+    const buildOpenCodeUrl = vi.fn(() => `http://127.0.0.1:${port}/global/event`);
+    const fetchImpl = vi.fn(async (_url, options) => {
+      fetchCalls += 1;
+      if (fetchCalls === 1) {
+        return createSseResponse({
+          signal: options.signal,
+          holdOpen: true,
+          blocks: ['id: evt-1\ndata: {"type":"server.connected","properties":{}}\n\n'],
+        });
+      }
+      return createSseResponse({
+        signal: options.signal,
+        holdOpen: true,
+        blocks: ['id: evt-2\ndata: {"type":"session.updated","properties":{"sessionID":"ses_1"}}\n\n'],
+      });
+    });
+
+    const globalHub = createGlobalMessageStreamHub({
+      buildOpenCodeUrl,
+      getOpenCodeAuthHeaders: () => ({}),
+      fetchImpl,
+      upstreamReconnectDelayMs: 0,
+    });
+
+    const runtime = createMessageStreamWsRuntime({
+      server,
+      uiAuthController: null,
+      isRequestOriginAllowed: async () => true,
+      rejectWebSocketUpgrade() {
+        throw new Error('upgrade should not be used in this test');
+      },
+      globalEventHub: globalHub,
+      buildOpenCodeUrl,
+      getOpenCodeAuthHeaders: () => ({}),
+      processForwardedEventPayload() {},
+      wsClients,
+      heartbeatIntervalMs: 5000,
+      upstreamReconnectDelayMs: 0,
+      fetchImpl,
+    });
+
+    const socket = new FakeSocket();
+    runtime.wsServer.emit('connection', socket, { url: '/api/global/event/ws' });
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    expect(fetchCalls).toBe(1);
+    expect(socket.sent.some((frame) => frame.type === 'event' && frame.eventId === 'evt-1')).toBe(true);
+
+    // The managed process was restarted onto a new port while the old
+    // process's SSE stream stays open (orphaned survivor).
+    port = 5000;
+    runtime.rebindUpstream();
+    await new Promise((resolve) => setTimeout(resolve, 20));
+
+    // The hub dialed the new port and the connected client received events
+    // from the new upstream without reconnecting its own socket.
+    expect(fetchCalls).toBe(2);
+    expect(fetchImpl.mock.calls[1][0]).toContain(':5000/global/event');
+    expect(socket.sent.some((frame) => frame.type === 'event' && frame.eventId === 'evt-2')).toBe(true);
+
+    socket.close();
+    await runtime.close();
+  });
+
+  it('closes directory-scoped sockets so their pinned readers reconnect to the new port', async () => {
+    const server = new EventEmitter();
+    const wsClients = new Set();
+    let port = 4096;
+    let fetchCalls = 0;
+
+    const buildOpenCodeUrl = vi.fn(() => `http://127.0.0.1:${port}/event`);
+    const fetchImpl = vi.fn(async (_url, options) => {
+      fetchCalls += 1;
+      return createSseResponse({
+        signal: options.signal,
+        holdOpen: true,
+        blocks: ['id: evt-1\ndata: {"type":"server.connected","properties":{}}\n\n'],
+      });
+    });
+
+    const runtime = createMessageStreamWsRuntime({
+      server,
+      uiAuthController: null,
+      isRequestOriginAllowed: async () => true,
+      rejectWebSocketUpgrade() {
+        throw new Error('upgrade should not be used in this test');
+      },
+      buildOpenCodeUrl,
+      getOpenCodeAuthHeaders: () => ({}),
+      processForwardedEventPayload() {},
+      wsClients,
+      heartbeatIntervalMs: 5000,
+      upstreamReconnectDelayMs: 0,
+      fetchImpl,
+    });
+
+    const directorySocket = new FakeSocket();
+    runtime.wsServer.emit('connection', directorySocket, { url: '/api/event/ws?directory=%2Fproj' });
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    expect(fetchCalls).toBe(1);
+
+    port = 5000;
+    runtime.rebindUpstream();
+
+    expect(directorySocket.readyState).toBe(3);
+    expect(directorySocket.closeCalls.length).toBeGreaterThan(0);
+
+    directorySocket.close();
+    await runtime.close();
+  });
+});
diff --git a/packages/web/server/lib/event-stream/runtime.js b/packages/web/server/lib/event-stream/runtime.js
index 72a28893..07b025dc 100644
--- a/packages/web/server/lib/event-stream/runtime.js
+++ b/packages/web/server/lib/event-stream/runtime.js
@@ -70,6 +70,12 @@ export function createMessageStreamWsRuntime({
     noServer: true,
   });
 
+  // Directory-scoped streams create one upstream reader per client
+  // connection. Track those sockets so a managed OpenCode restart can close
+  // them: each reader is pinned to the port it connected at and would
+  // otherwise keep streaming from an orphaned process on the old port (#2638).
+  const directorySockets = new Set();
+
   const ownsGlobalHub = !globalEventHub;
   const globalHub = globalEventHub ?? createGlobalMessageStreamHub({
     buildOpenCodeUrl,
@@ -103,6 +109,11 @@ export function createMessageStreamWsRuntime({
       return;
     }
 
+    directorySockets.add(socket);
+    socket.on('close', () => {
+      directorySockets.delete(socket);
+    });
+
     acceptDirectoryMessageStreamWsConnection({
       socket,
       requestedLastEventId,
@@ -156,6 +167,27 @@ export function createMessageStreamWsRuntime({
 
   return {
     wsServer,
+    /**
+     * Rebind all upstream readers to the current OpenCode port. Called after
+     * a managed process restart: the restart can land on a NEW port while
+     * the old process (or an orphaned survivor of it) still holds the
+     * previous one, and a healthy-but-pinned SSE connection never notices —
+     * so the UI would stop receiving events until the app restarts (#2638).
+     * Restarting the shared hub re-dials `buildOpenCodeUrl` (which reads the
+     * current port) on its next attempt; directory-scoped readers are
+     * rebuilt by closing their client sockets, which reconnect with
+     * `Last-Event-ID` and re-establish the stream against the new port.
+     */
+    rebindUpstream() {
+      globalHub.stop();
+      globalHub.start();
+      for (const socket of Array.from(directorySockets)) {
+        try {
+          socket.close(1012, 'OpenCode upstream restarted');
+        } catch {
+        }
+      }
+    },
     async close() {
       server.off('upgrade', upgradeHandler);
       globalBridge.close();
diff --git a/packages/web/server/lib/opencode/lifecycle.js b/packages/web/server/lib/opencode/lifecycle.js
index 172d88b2..bb13aab0 100644
--- a/packages/web/server/lib/opencode/lifecycle.js
+++ b/packages/web/server/lib/opencode/lifecycle.js
@@ -48,6 +48,7 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
     getActiveSessionCount = () => 0,
     reapManagedOrphanedProcesses = reapOrphanedProcesses,
     getWarmupDirectories = async () => [],
+    onOpenCodeRestarted = null,
     now = Date.now,
   } = deps;
 
@@ -694,6 +695,17 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
         setupProxy(state.expressApp);
         ensureOpenCodeApiPrefix();
       }
+
+      // The restart may have landed on a NEW port (the old one can remain
+      // occupied by an orphaned process, e.g. Windows killProcessOnPort is a
+      // no-op). Upstream event readers pinned to the old process would keep
+      // the UI silent forever, so rebind them to the current port. Best
+      // effort: a failure here must not fail the restart itself.
+      try {
+        onOpenCodeRestarted?.();
+      } catch (error) {
+        console.warn('Failed to rebind event stream after OpenCode restart:', error?.message ?? error);
+      }
     })();
 
     try {
diff --git a/packages/web/server/lib/opencode/lifecycle.test.js b/packages/web/server/lib/opencode/lifecycle.test.js
index fb57c3f2..04bf4c33 100644
--- a/packages/web/server/lib/opencode/lifecycle.test.js
+++ b/packages/web/server/lib/opencode/lifecycle.test.js
@@ -286,6 +286,70 @@ describe('OpenCode lifecycle', () => {
     expect(spawnMock).toHaveBeenCalledTimes(1);
   });
 
+  it('calls onOpenCodeRestarted after a successful managed restart', async () => {
+    const close = vi.fn(async () => {});
+    const replacement = createMockChild();
+    const onOpenCodeRestarted = vi.fn();
+    globalThis.fetch = vi.fn(async () => ({
+      ok: false,
+      json: async () => null,
+    }));
+    spawnMock.mockImplementationOnce(() => {
+      queueMicrotask(() => {
+        replacement.stdout.emit('data', 'opencode server listening on http://127.0.0.1:45678\n');
+      });
+      return replacement;
+    });
+    const runtime = createRuntime({ onOpenCodeRestarted }, {
+      openCodePort: 45678,
+      openCodeProcess: {
+        pid: null,
+        exitCode: 1,
+        signalCode: null,
+        close,
+      },
+    });
+
+    await runtime.triggerHealthCheck();
+
+    expect(close).toHaveBeenCalledTimes(1);
+    expect(spawnMock).toHaveBeenCalledTimes(1);
+    // The restart completed on a (possibly new) port — the event-stream
+    // upstreams must rebind so the UI keeps receiving events (#2638).
+    expect(onOpenCodeRestarted).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not call onOpenCodeRestarted when a managed restart fails', async () => {
+    const close = vi.fn(async () => {});
+    const onOpenCodeRestarted = vi.fn();
+    globalThis.fetch = vi.fn(async () => ({
+      ok: false,
+      json: async () => null,
+    }));
+    spawnMock.mockImplementation(() => {
+      const child = createMockChild();
+      queueMicrotask(() => {
+        child.emit('error', new Error('spawn failed'));
+      });
+      return child;
+    });
+    const runtime = createRuntime({ onOpenCodeRestarted }, {
+      openCodePort: 45678,
+      openCodeProcess: {
+        pid: null,
+        exitCode: 1,
+        signalCode: null,
+        close,
+      },
+    });
+
+    // triggerHealthCheck logs instead of rethrowing; call restartOpenCode
+    // directly to observe the failure result.
+    await expect(runtime.restartOpenCode()).rejects.toThrow();
+
+    expect(onOpenCodeRestarted).not.toHaveBeenCalled();
+  });
+
   it('launches managed OpenCode with the managed PATH', async () => {
     delete process.env.OPENCODE_BINARY;
     const child = createMockChild();
diff --git a/scripts/repro/issue-2638/README.md b/scripts/repro/issue-2638/README.md
new file mode 100644
index 00000000..357ee8af
--- /dev/null
+++ b/scripts/repro/issue-2638/README.md
@@ -0,0 +1,47 @@
+# Reproduction: Chat UI stops updating until the desktop app is restarted (#2638)
+
+Reproduces https://github.com/openchamber/openchamber/issues/2638 using the
+real server modules (`lifecycle.js`, `global-hub.js`, `network-runtime.js`),
+real processes, and real ports — no mocks.
+
+## Run
+
+```sh
+# Windows-orphan scenario (the reported bug):
+node scripts/repro/issue-2638/reproduce-2638.mjs
+
+# Control: healthy restart on Linux (hub reconnects, UI keeps updating):
+node scripts/repro/issue-2638/reproduce-2638.mjs --baseline
+```
+
+Requires `lsof` (used only for cleanup). The default run simulates Windows
+(`process.platform` is temporarily overridden to `win32`) because the bug is
+specific to the Windows process-lifecycle path.
+
+## What it demonstrates
+
+1. A managed OpenCode process starts; the global message-stream hub connects to
+   its `/global/event` SSE stream and chat events flow to the UI.
+2. The managed process "exits" but the actual server process survives on the
+   old port (on Windows `killProcessOnPort` is a no-op and `taskkill` cannot
+   reach the orphaned tree — the report shows leftover `opencode.exe serve`
+   processes on historical ports).
+3. `restartOpenCode()` gives up after 5 s — logs
+   `Timed out waiting for OpenCode port <old> to be released` — and spawns a
+   fresh server on a NEW port, leaving the orphaned process running.
+4. HTTP/proxy traffic follows `state.openCodePort` to the new server, but the
+   hub's upstream SSE reader stays pinned to the OLD server's `/global/event`
+   stream (that connection never closed), so events emitted by the new server
+   never reach the UI: the chat UI goes stale while the new server keeps
+   persisting session data — visible only after restarting the app.
+
+The `--baseline` control proves the reconnect logic itself is fine: when the
+old process dies and the port is properly released, the hub reconnects to the
+new port and events are delivered.
+
+## Files
+
+- `reproduce-2638.mjs` — the reproduction driver (assertions + summary).
+- `fake-opencode-serve.mjs` — a fake `opencode serve` binary whose launcher
+  spawns a detached server core that survives the launcher's death
+  (Windows-style orphan), plus an in-process mode for the baseline control.
diff --git a/scripts/repro/issue-2638/fake-opencode-serve.mjs b/scripts/repro/issue-2638/fake-opencode-serve.mjs
new file mode 100755
index 00000000..0fc36dc0
--- /dev/null
+++ b/scripts/repro/issue-2638/fake-opencode-serve.mjs
@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+// Fake `opencode serve` used to reproduce https://github.com/openchamber/openchamber/issues/2638
+//
+// Modes (controlled by env):
+//   FAKE_OPENCODE_CORE=1      – server-core mode: binds the port, serves
+//                               /global/health + SSE /global/event, ignores
+//                               SIGTERM so it survives its launcher's death
+//                               (Windows-style orphaned server process).
+//   FAKE_OPENCODE_BASELINE=1  – in-process mode: the server runs inside the
+//                               managed process and dies with it (normal
+//                               Linux behavior used as a control).
+//   default (launcher)        – spawns a detached core grandchild, waits for
+//                               it to bind, prints the `opencode server
+//                               listening on ...` line the lifecycle greps
+//                               for, stays alive, and on SIGTERM exits WITHOUT
+//                               killing the core (mimics opencode.exe dying
+//                               while its server child survives).
+import http from 'node:http';
+import net from 'node:net';
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+
+const args = process.argv.slice(2);
+const portIndex = args.indexOf('--port');
+const hostnameIndex = args.indexOf('--hostname');
+const port = portIndex >= 0 ? Number(args[portIndex + 1]) : 0;
+const hostname = hostnameIndex >= 0 ? args[hostnameIndex + 1] : '127.0.0.1';
+const pidDir = process.env.FAKE_OPENCODE_PID_DIR || null;
+
+function writePidFile(label) {
+  if (!pidDir) return;
+  try {
+    fs.mkdirSync(pidDir, { recursive: true });
+    fs.writeFileSync(path.join(pidDir, `${label}-${port}.pid`), String(process.pid));
+  } catch {
+    // best effort
+  }
+}
+
+function createServer() {
+  const clients = new Set();
+  const emitted = [];
+  const server = http.createServer((req, res) => {
+    const url = new URL(req.url, `http://${hostname}:${port}`);
+    if (url.pathname === '/global/health') {
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ healthy: true }));
+      return;
+    }
+    if (url.pathname === '/global/event') {
+      res.writeHead(200, {
+        'content-type': 'text/event-stream',
+        'cache-control': 'no-cache',
+        connection: 'keep-alive',
+      });
+      clients.add(res);
+      req.on('close', () => clients.delete(res));
+      // SSE keep-alive comments — exactly what a real OpenCode server sends,
+      // which prevents the upstream reader's 20s stall timer from firing.
+      const keepalive = setInterval(() => {
+        res.write(': keepalive\n\n');
+      }, 1000);
+      req.on('close', () => clearInterval(keepalive));
+      return;
+    }
+    if (url.pathname === '/emit') {
+      const type = url.searchParams.get('type') || 'session.updated';
+      const id = url.searchParams.get('id') || `evt-${Date.now()}`;
+      emitted.push({ id, type });
+      const block = `id: ${id}\ndata: ${JSON.stringify({ type, id })}\n\n`;
+      for (const client of clients) client.write(block);
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ ok: true, id }));
+      return;
+    }
+    if (url.pathname === '/events') {
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify(emitted));
+      return;
+    }
+    res.writeHead(404);
+    res.end('not found');
+  });
+  return { server };
+}
+
+const runServer = (label) => {
+  createServer().server.listen(port, hostname, () => {
+    console.log(`opencode server listening on http://${hostname}:${port}`);
+  });
+  writePidFile(label);
+  setInterval(() => {}, 1 << 30);
+};
+
+const main = async () => {
+  // Server-core mode: the orphaned server. Survives its launcher's death.
+  if (process.env.FAKE_OPENCODE_CORE === '1') {
+    runServer('core');
+    process.on('SIGTERM', () => {});
+    process.on('SIGINT', () => {});
+    return;
+  }
+
+  // Baseline in-process mode (control): dies with the managed process, so the
+  // port is properly released on restart.
+  if (process.env.FAKE_OPENCODE_BASELINE === '1') {
+    runServer('baseline');
+    return;
+  }
+
+  // Launcher mode: spawn a detached core grandchild, wait for it to bind,
+  // print the listening line, and on SIGTERM exit leaving the core running.
+  const core = spawn(process.execPath, [process.argv[1], ...args], {
+    detached: true,
+    stdio: ['ignore', 'ignore', 'ignore'],
+    env: { ...process.env, FAKE_OPENCODE_CORE: '1' },
+  });
+  core.unref();
+
+  for (let i = 0; i < 200; i += 1) {
+    if (core.exitCode !== null) throw new Error('core exited early');
+    const ok = await new Promise((resolve) => {
+      const socket = net.connect({ port, host: hostname });
+      const timer = setTimeout(() => {
+        socket.destroy();
+        resolve(false);
+      }, 200);
+      socket.once('connect', () => {
+        clearTimeout(timer);
+        socket.destroy();
+        resolve(true);
+      });
+      socket.once('error', () => {
+        clearTimeout(timer);
+        resolve(false);
+      });
+    });
+    if (ok) break;
+    await new Promise((r) => setTimeout(r, 50));
+  }
+
+  writePidFile('launcher');
+  console.log(`opencode server listening on http://${hostname}:${port}`);
+  // On SIGTERM exit ourselves, leaving the detached core running.
+  process.on('SIGTERM', () => process.exit(0));
+  process.on('SIGINT', () => process.exit(0));
+  setInterval(() => {}, 1 << 30);
+};
+
+await main();
diff --git a/scripts/repro/issue-2638/reproduce-2638.mjs b/scripts/repro/issue-2638/reproduce-2638.mjs
new file mode 100644
index 00000000..d4f99af4
--- /dev/null
+++ b/scripts/repro/issue-2638/reproduce-2638.mjs
@@ -0,0 +1,376 @@
+// Reproduction for https://github.com/openchamber/openchamber/issues/2638
+// "[Bug] Chat UI stops updating until the desktop app is restarted"
+//
+// Run with:  node reproduce-2638.mjs          (Windows-orphan scenario)
+//            node reproduce-2638.mjs --baseline (control: healthy restart)
+//
+// What it wires up (real repo modules, real processes, real ports):
+//   - createOpenCodeLifecycleRuntime (packages/web/server/lib/opencode/lifecycle.js)
+//   - createGlobalMessageStreamHub   (packages/web/server/lib/event-stream/global-hub.js)
+//   - createOpenCodeNetworkRuntime   (packages/web/server/lib/opencode/network-runtime.js)
+//   - a fake `opencode serve` binary (fake-opencode-serve.mjs)
+//
+// Scenario (issue #2638):
+//   1. OpenCode starts; the global message-stream hub connects to its
+//      /global/event SSE stream. Chat UI updates flow (baseline event e1
+//      reaches the hub).
+//   2. The managed OpenCode process "exits" but the actual server process
+//      survives on the old port (on Windows killProcessOnPort is a no-op and
+//      taskkill cannot reach the orphaned tree — the report shows leftover
+//      `opencode.exe serve` processes on historical ports).
+//   3. restartOpenCode() gives up after 5 s
+//      ("Timed out waiting for OpenCode port <old> to be released") and
+//      spawns a fresh server on a NEW port.
+//   4. HTTP/proxy traffic follows state.openCodePort to the NEW server, but
+//      the hub's upstream SSE reader is still pinned to the OLD server's
+//      /global/event stream (that connection never closed), so events from
+//      the new server never reach the UI. Chat UI goes stale while the new
+//      server keeps persisting session data — visible only after restarting
+//      the app, exactly as reported.
+
+import { spawnSync } from 'node:child_process';
+import net from 'node:net';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Repository root (override with REPO=/path/to/openchamber if needed). Default:
+// walk up from this script until we find the repo root (AGENTS.md + package.json).
+const findRepoRoot = () => {
+  let dir = __dirname;
+  for (let i = 0; i < 8; i += 1) {
+    if (fs.existsSync(path.join(dir, 'AGENTS.md')) && fs.existsSync(path.join(dir, 'package.json'))) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return '/home/runner/work/openchamber/openchamber';
+};
+const REPO = process.env.REPO || findRepoRoot();
+
+const BASELINE = process.argv.includes('--baseline');
+
+// Simulate the Windows behavior reported in #2638 (process.platform is read
+// at call time inside lifecycle.js: killProcessOnPort no-ops on win32 and
+// terminateChildProcess takes the taskkill path, which cannot exist here).
+if (!BASELINE) {
+  Object.defineProperty(process, 'platform', { value: 'win32' });
+}
+
+const { createOpenCodeLifecycleRuntime } = await import(
+  path.join(REPO, 'packages/web/server/lib/opencode/lifecycle.js')
+);
+
+// --- shared state + real network runtime -----------------------------------
+const state = {
+  openCodeWorkingDirectory: '/tmp',
+  openCodeProcess: null,
+  openCodePort: null,
+  openCodeBaseUrl: null,
+  currentRestartPromise: null,
+  isRestartingOpenCode: false,
+  openCodeApiPrefix: '',
+  openCodeApiPrefixDetected: false,
+  openCodeApiDetectionTimer: null,
+  lastOpenCodeError: null,
+  isOpenCodeReady: false,
+  openCodeNotReadySince: 0,
+  isExternalOpenCode: false,
+  isShuttingDown: false,
+  healthCheckInterval: null,
+  expressApp: null,
+  useWslForOpencode: false,
+  resolvedWslBinary: null,
+  resolvedWslOpencodePath: null,
+  resolvedWslDistro: null,
+  lastOpenCodeLaunchDiagnostics: null,
+};
+
+const { createOpenCodeNetworkRuntime } = await import(
+  path.join(REPO, 'packages/web/server/lib/opencode/network-runtime.js')
+);
+const networkRuntime = createOpenCodeNetworkRuntime({
+  state,
+  getOpenCodeAuthHeaders: () => ({}),
+  configuredOpenCodeHostname: '127.0.0.1',
+});
+
+const fakeBinary = path.join(__dirname, 'fake-opencode-serve.mjs');
+const pidDir = fs.mkdtempSync(path.join(os.tmpdir(), 'oc-repro-2638-'));
+process.env.OPENCODE_BINARY = fakeBinary;
+process.env.FAKE_OPENCODE_PID_DIR = pidDir;
+if (BASELINE) process.env.FAKE_OPENCODE_BASELINE = '1';
+
+const lifecycle = createOpenCodeLifecycleRuntime({
+  state,
+  env: {
+    ENV_CONFIGURED_OPENCODE_PORT: 0,
+    ENV_CONFIGURED_OPENCODE_HOST: null,
+    ENV_EFFECTIVE_PORT: 0,
+    ENV_CONFIGURED_OPENCODE_HOSTNAME: '127.0.0.1',
+    ENV_SKIP_OPENCODE_START: false,
+  },
+  syncToHmrState: () => {},
+  syncFromHmrState: () => {},
+  getOpenCodeAuthHeaders: () => ({}),
+  buildOpenCodeUrl: (...args) => networkRuntime.buildOpenCodeUrl(...args),
+  waitForReady: (...args) => networkRuntime.waitForReady(...args),
+  normalizeApiPrefix: (...args) => networkRuntime.normalizeApiPrefix(...args),
+  applyOpencodeBinaryFromSettings: async () => {},
+  ensureOpencodeCliEnv: () => {},
+  ensureLocalOpenCodeServerPassword: async () => 'password',
+  resolveManagedOpenCodeLaunchSpec: (binary) => ({ binary, args: [], wrapperType: null }),
+  setOpenCodePort: (port) => { state.openCodePort = port; },
+  setDetectedOpenCodeApiPrefix: () => {},
+  setupProxy: () => {},
+  ensureOpenCodeApiPrefix: () => {},
+  clearResolvedOpenCodeBinary: () => {},
+  buildAugmentedPath: () => process.env.PATH,
+  buildManagedOpenCodePath: () => process.env.PATH,
+  getManagedOpenCodeShellEnvSnapshot: async () => ({}),
+  getManagedOpenCodeEnv: async () => ({}),
+  reapManagedOrphanedProcesses: async () => ({ reaped: 0 }),
+  getWarmupDirectories: async () => [],
+  // Production index.js wires this to the message-stream runtime's
+  // rebindUpstream(); mirror it here so the harness exercises the fix.
+  onOpenCodeRestarted: () => {
+    try {
+      rebindHub?.();
+    } catch {
+    }
+  },
+});
+
+const { createGlobalMessageStreamHub } = await import(
+  path.join(REPO, 'packages/web/server/lib/event-stream/global-hub.js')
+);
+
+// The hub represents the server→OpenCode SSE push pipeline that feeds the
+// renderer (both the server-side PushWatcher and the browser WS bridge).
+const received = [];
+const statuses = [];
+let rebindHub = null;
+const hub = createGlobalMessageStreamHub({
+  buildOpenCodeUrl: (p) => networkRuntime.buildOpenCodeUrl(p, ''),
+  getOpenCodeAuthHeaders: () => ({}),
+  upstreamStallTimeoutMs: 20000,
+  upstreamReconnectDelayMs: 250,
+});
+hub.subscribeEvent(({ eventId, payload }) => {
+  received.push({ eventId, type: payload?.type, id: payload?.id });
+});
+hub.subscribeStatus((status) => statuses.push(status));
+rebindHub = () => {
+  hub.stop();
+  hub.start();
+};
+
+// --- helpers ----------------------------------------------------------------
+const warnLog = [];
+const origWarn = console.warn;
+console.warn = (...args) => {
+  warnLog.push(args.map(String).join(' '));
+  origWarn(...args);
+};
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+async function waitFor(fn, timeoutMs, what) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await fn()) return true;
+    await sleep(50);
+  }
+  throw new Error(`timeout waiting for ${what}`);
+}
+
+const emitEvent = async (port, id, type = 'session.updated') => {
+  const res = await fetch(`http://127.0.0.1:${port}/emit?type=${type}&id=${id}`);
+  if (!res.ok) throw new Error(`emit ${id} failed on port ${port}`);
+  return res.json();
+};
+
+const persistedEvents = async (port) => {
+  const res = await fetch(`http://127.0.0.1:${port}/events`);
+  return res.ok ? res.json() : [];
+};
+
+const portOpen = (port) => new Promise((resolve) => {
+  const socket = net.connect({ port, host: '127.0.0.1' });
+  const timer = setTimeout(() => { socket.destroy(); resolve(false); }, 300);
+  socket.once('connect', () => { clearTimeout(timer); socket.destroy(); resolve(true); });
+  socket.once('error', () => { clearTimeout(timer); resolve(false); });
+});
+
+const pidFilePids = () => {
+  const out = [];
+  for (const file of fs.readdirSync(pidDir)) {
+    if (!file.endsWith('.pid')) continue;
+    try {
+      out.push({ label: file.replace(/\.pid$/, ''), pid: Number(fs.readFileSync(path.join(pidDir, file), 'utf8')) });
+    } catch {
+      // ignore
+    }
+  }
+  return out;
+};
+
+const killPortPids = (port) => {
+  try {
+    const result = spawnSync('lsof', ['-ti', `:${port}`], { encoding: 'utf8' });
+    const pids = String(result.stdout || '').trim().split(/\s+/).map(Number).filter(Boolean);
+    for (const pid of pids) {
+      if (pid === process.pid) continue; // never kill ourselves (TIME_WAIT client sockets)
+      try { process.kill(pid, 'SIGKILL'); } catch { /* already gone */ }
+    }
+  } catch { /* lsof unavailable */ }
+};
+
+const cleanup = async () => {
+  for (const { label, pid } of pidFilePids()) {
+    if (label.startsWith('launcher') || label.startsWith('baseline')) {
+      try { process.kill(pid, 'SIGTERM'); } catch { /* gone */ }
+    } else {
+      try { process.kill(pid, 'SIGKILL'); } catch { /* gone */ }
+    }
+  }
+  if (state.openCodePort) killPortPids(state.openCodePort);
+  // Belt and braces: kill any surviving fake-opencode processes from this run.
+  try {
+    const result = spawnSync('pgrep', ['-f', 'fake-opencode-serve.mjs'], { encoding: 'utf8' });
+    const pids = String(result.stdout || '').trim().split(/\s+/).map(Number).filter(Boolean);
+    for (const pid of pids) {
+      if (pid === process.pid) continue;
+      try { process.kill(pid, 'SIGKILL'); } catch { /* gone */ }
+    }
+  } catch { /* pgrep unavailable */ }
+  await sleep(300);
+  try { fs.rmSync(pidDir, { recursive: true, force: true }); } catch { /* ignore */ }
+  console.warn = origWarn;
+};
+
+// --- run ---------------------------------------------------------------------
+console.log(`\n=== reproduce-2638 (${BASELINE ? 'BASELINE control' : 'Windows-orphan scenario'}) ===\n`);
+let failures = 0;
+const check = (label, ok, detail = '') => {
+  console.log(`  ${ok ? 'PASS' : 'FAIL'}  ${label}${detail ? ` — ${detail}` : ''}`);
+  if (!ok) failures += 1;
+};
+
+try {
+  // 1. Bootstrapping starts the managed OpenCode (launcher + server core) on P1.
+  await lifecycle.bootstrapOpenCodeAtStartup();
+  const p1 = state.openCodePort;
+  console.log(`[1] bootstrap OK — managed OpenCode listening on port ${p1} (pid ${state.openCodeProcess?.pid})`);
+
+  // 2. Connect the message-stream hub (server→OpenCode SSE push pipeline).
+  hub.start();
+  await waitFor(() => statuses.some((s) => s.type === 'connect'), 10000, 'hub connect to P1');
+  console.log('[2] message-stream hub connected to /global/event');
+
+  // 3. Baseline delivery: an event emitted by P1 reaches the UI pipeline.
+  await emitEvent(p1, 'evt-before-restart');
+  await waitFor(() => received.some((r) => r.eventId === 'evt-before-restart'), 5000, 'event delivery');
+  check('events flow to the UI before the restart (baseline)', received.some((r) => r.eventId === 'evt-before-restart'));
+
+  // 4. The managed process "exits" while the actual server survives on P1
+  //    (simulates the Windows orphan: launcher dies, server core keeps the
+  //    port and the SSE stream). In baseline mode the server runs in-process
+  //    and dies with the managed process instead.
+  const launcherPid = state.openCodeProcess.pid;
+  process.kill(launcherPid, 'SIGTERM');
+  await waitFor(async () => {
+    try { process.kill(launcherPid, 0); return false; } catch { return true; }
+  }, 5000, 'launcher exit');
+  console.log(`[4] managed process (pid ${launcherPid}) exited; ${BASELINE ? 'server process died with it' : `orphaned server core still listening on ${p1}`}`);
+
+  // 5. Trigger the reported restart path ("Refreshing OpenCode after manual
+  //    configuration reload" / periodic health check).
+  console.log('[5] triggering restart (refreshOpenCodeAfterConfigChange)...');
+  await lifecycle.refreshOpenCodeAfterConfigChange('manual configuration reload');
+  const p2 = state.openCodePort;
+  console.log(`[5] restarted — new managed OpenCode listening on port ${p2}`);
+
+  // 6. Assert the reported log line: the old port was never released. In the
+  //    baseline control the port IS released, so the warning must be absent.
+  const timeoutWarn = warnLog.find((line) => line.includes('Timed out waiting for OpenCode port') && line.includes(String(p1)));
+  if (BASELINE) {
+    check(`no "Timed out waiting for OpenCode port ${p1}" warning in baseline control`, !timeoutWarn);
+  } else {
+    check(`"Timed out waiting for OpenCode port ${p1} to be released" is logged`, Boolean(timeoutWarn), timeoutWarn || '');
+  }
+  check('new port differs from old port (leaked process pinned the old one)', p2 !== p1, `p1=${p1} p2=${p2}`);
+
+  // 7. Assert the orphaned old server is still running (process pile-up from
+  //    the report: "six opencode.exe serve processes were still running").
+  //    In baseline mode we instead expect the port to be properly released.
+  const oldCoreStillUp = await portOpen(p1);
+  const pids = pidFilePids();
+  const orphanPids = pids.filter(({ label }) => label.startsWith('core')).map(({ pid }) => pid);
+  const orphanAlive = orphanPids.length > 0 && orphanPids.every((pid) => {
+    try { process.kill(pid, 0); return true; } catch { return false; }
+  });
+  if (BASELINE) {
+    check('old port properly released (no orphan in baseline control)', !oldCoreStillUp,
+      `old port ${p1} ${oldCoreStillUp ? 'still open' : 'released'}`);
+  } else {
+    check('orphaned server process still running on the old port', oldCoreStillUp && orphanAlive,
+      `old port ${p1} still open; orphan core pids ${orphanPids.join(', ')}`);
+  }
+
+  // 8. The stale-UI reproduction: the new server persists events, but in the
+  //    orphan scenario they never reach the UI because the hub is still pinned
+  //    to the old SSE stream. In baseline mode the hub must reconnect to the
+  //    new port and deliver them (wait for the reconnect before emitting —
+  //    the upstream reader only learns about the new port on its next attempt).
+  const connectsBefore = statuses.filter((s) => s.type === 'connect').length;
+  if (!BASELINE) {
+    await sleep(1000);
+  } else {
+    await waitFor(() => statuses.filter((s) => s.type === 'connect').length >= connectsBefore + 1, 15000, 'hub reconnect to new port');
+  }
+  await emitEvent(p2, 'evt-after-restart');
+  console.log(`[8] emitted evt-after-restart on new port ${p2} — waiting to see if the UI receives it...`);
+  await sleep(2500);
+  const deliveredAfter = received.filter((r) => r.eventId === 'evt-after-restart').length;
+  if (BASELINE) {
+    check('NEW server event IS delivered to the UI (hub reconnected in baseline)', deliveredAfter === 1,
+      `delivered=${deliveredAfter}, total hub events=${received.length}`);
+  } else {
+    // Fixed: the lifecycle hook rebinds the hub after the managed restart,
+    // so the UI receives events from the new port even when the old port is
+    // orphaned. The wait mirrors the baseline branch (the reader re-dials on
+    // its next attempt after the rebind).
+    await waitFor(() => statuses.filter((s) => s.type === 'connect').length >= connectsBefore + 1, 15000, 'hub reconnect to new port after rebind');
+    check('NEW server event IS delivered to the UI (rebound after restart)', deliveredAfter === 1,
+      `delivered=${deliveredAfter}, total hub events=${received.length}`);
+  }
+
+  const persistedOnNew = await persistedEvents(p2);
+  check('NEW server persisted the event (data survives, UI does not show it)', persistedOnNew.some((e) => e.id === 'evt-after-restart'),
+    `persisted on port ${p2}: ${JSON.stringify(persistedOnNew)}`);
+
+  // 9. Orphan scenario: with the rebind the hub is no longer pinned to the
+  //    old server — events emitted by the old (zombie) server must NOT reach
+  //    the UI anymore (it left the previous upstream behind).
+  if (!BASELINE) {
+    await emitEvent(p1, 'evt-zombie-old-server');
+    await sleep(2000);
+    check('OLD zombie server events no longer reach the UI (hub rebound to new upstream)', !received.some((r) => r.eventId === 'evt-zombie-old-server'));
+  }
+
+  console.log(`\n=== ${failures === 0 ? 'REPRODUCED (all checks passed)' : `${failures} check(s) FAILED`} ===\n`);
+  console.log(`hub statuses observed: ${JSON.stringify(statuses)}`);
+} catch (error) {
+  console.error('\nReproduction script error:', error);
+  failures += 1;
+} finally {
+  await cleanup();
+}
+
+process.exit(failures === 0 ? 0 : 1);

From 2fcfe511a5336fab4c6003ee5c47e25938c98534 Mon Sep 17 00:00:00 2001
From: Serhii Dziupin <serkraser@gmail.com>
Date: Wed, 5 Aug 2026 14:11:28 +0300
Subject: [PATCH 26/57] feat(tasks): support markdown scheduled-task loops in
 .agents/loops

Adds markdown-based scheduled-task definitions ("loops") discovered from
.agents/loops/*.md (project scope, ancestor directories up to the
worktree root) and ~/.agents/loops/*.md (user scope), mirroring the
skills discovery pattern.

File format: YAML frontmatter (name, schedule cron, enabled, model as
provider/model, optional agent/timezone) plus the markdown body as the
execution prompt. Discovery and parsing live in
scheduled-tasks/loops.js; project-config gains reconcileLoopTasks which
runs inside the project write lock on every syncProject:
- identity by task name; a loop takes over a matching task, preserving
  its id and runtime state (markdown wins on conflict with JSON)
- tasks whose loopFile is gone are unscheduled; JSON tasks are never
  removed
- new loops are created under deterministic loop:<scope>:<name> ids
- project scope shadows user scope on name collisions
- malformed files are skipped with a warning and never block valid ones

Runtime state stays in the project config/state store; it is never
written to the markdown files. Module documentation updated with the
file format and reconciliation rules.

Fixes #2583
---
 .../web/server/lib/projects/project-config.js | 101 ++++++
 .../lib/projects/project-config.test.js       | 159 ++++++++-
 .../lib/scheduled-tasks/DOCUMENTATION.md      |  66 +++-
 .../web/server/lib/scheduled-tasks/loops.js   | 189 ++++++++++
 .../server/lib/scheduled-tasks/loops.test.js  | 335 ++++++++++++++++++
 .../web/server/lib/scheduled-tasks/runtime.js |  14 +-
 6 files changed, 861 insertions(+), 3 deletions(-)
 create mode 100644 packages/web/server/lib/scheduled-tasks/loops.js
 create mode 100644 packages/web/server/lib/scheduled-tasks/loops.test.js

diff --git a/packages/web/server/lib/projects/project-config.js b/packages/web/server/lib/projects/project-config.js
index ed8d98b6..453d487f 100644
--- a/packages/web/server/lib/projects/project-config.js
+++ b/packages/web/server/lib/projects/project-config.js
@@ -313,6 +313,11 @@ const normalizeTaskForStorage = (value, options) => {
   const schedule = normalizeSchedule(value.schedule, existingTask?.schedule);
   const execution = normalizeExecution(value.execution);
 
+  // Loop provenance: absolute path of the `.agents/loops/*.md` file driving
+  // this task, when any. Preserved on every write so the scheduler can detect
+  // removed loop files across restarts. Unknown to the UI model.
+  const loopFile = asNonEmptyString(value.loopFile) ?? asNonEmptyString(existingTask?.loopFile);
+
   const nowMs = Math.max(0, Math.round(now));
   const baseState = normalizeState(value.state, existingTask?.state);
   const state = {
@@ -328,6 +333,7 @@ const normalizeTaskForStorage = (value, options) => {
     schedule,
     execution,
     state,
+    ...(loopFile ? { loopFile } : {}),
   };
 };
 
@@ -559,11 +565,106 @@ export const createProjectConfigRuntime = (deps) => {
     });
   };
 
+  /**
+   * Reconcile discovered `.agents/loops` definitions with the persisted JSON
+   * task list.
+   *
+   * Rules (documented in scheduled-tasks/DOCUMENTATION.md):
+   * - Identity is the task NAME. A loop whose name matches an existing task
+   *   takes that task over: its schedule/execution/enabled are overwritten
+   *   from the file while its id and runtime state are preserved (markdown
+   *   wins on conflict).
+   * - A task whose loopFile no longer matches any discovered loop file is
+   *   unscheduled (removed). JSON-configured tasks (no loopFile) are never
+   *   removed.
+   * - Loops with no matching task are created under a deterministic
+   *   `loop:<scope>:<name>` id, so runtime state survives restarts.
+   * - Malformed definitions are skipped with a warning and never block valid
+   *   loops; the scheduler passes only parsed definitions, and normalization
+   *   failures here are isolated per loop.
+   */
+  const reconcileLoopTasks = async (projectID, loops) => {
+    return withProjectWriteLock(projectID, async () => {
+      const now = Date.now();
+      const current = await readProjectConfigFromDisk(projectID);
+      const tasks = current.scheduledTasks;
+
+      const activeLoopFilePaths = new Set();
+      const pendingLoops = new Map();
+      for (const loop of loops) {
+        if (!loop || !loop.definition || typeof loop.definition !== 'object') {
+          continue;
+        }
+        activeLoopFilePaths.add(loop.filePath);
+        pendingLoops.set(loop.definition.name, loop);
+      }
+
+      const nextTasks = [];
+      for (const task of tasks) {
+        if (task.loopFile && !activeLoopFilePaths.has(task.loopFile)) {
+          // The driving loop file was removed (or renamed) — unschedule.
+          continue;
+        }
+
+        const loop = pendingLoops.get(task.name);
+        if (loop) {
+          try {
+            const adopted = normalizeTaskForStorage(
+              { ...task, ...loop.definition, loopFile: loop.filePath },
+              {
+                now,
+                createId: taskIDFactory,
+                existingTask: task,
+                allowCreate: false,
+                refreshUpdatedAt: false,
+              },
+            );
+            nextTasks.push(adopted);
+            pendingLoops.delete(loop.definition.name);
+          } catch (error) {
+            console.warn(`[scheduled-tasks] skipped loop ${loop.filePath} for task "${task.name}":`, error?.message ?? error);
+            nextTasks.push(task);
+          }
+          continue;
+        }
+
+        nextTasks.push(task);
+      }
+
+      for (const loop of pendingLoops.values()) {
+        try {
+          const id = `loop:${loop.scope}:${loop.definition.name}`;
+          const created = normalizeTaskForStorage(
+            { id, ...loop.definition, loopFile: loop.filePath },
+            {
+              now,
+              createId: taskIDFactory,
+              existingTask: null,
+              allowCreate: true,
+              refreshUpdatedAt: false,
+            },
+          );
+          nextTasks.push(created);
+        } catch (error) {
+          console.warn(`[scheduled-tasks] skipped loop ${loop.filePath}:`, error?.message ?? error);
+        }
+      }
+
+      await writeProjectConfigToDisk(projectID, {
+        version: PROJECT_CONFIG_VERSION,
+        scheduledTasks: nextTasks,
+      });
+
+      return nextTasks;
+    });
+  };
+
   return {
     listScheduledTasks,
     upsertScheduledTask,
     deleteScheduledTask,
     updateScheduledTaskState,
+    reconcileLoopTasks,
     resolveProjectConfigPath,
   };
 };
diff --git a/packages/web/server/lib/projects/project-config.test.js b/packages/web/server/lib/projects/project-config.test.js
index ef7b5eb4..38122c3f 100644
--- a/packages/web/server/lib/projects/project-config.test.js
+++ b/packages/web/server/lib/projects/project-config.test.js
@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import os from 'os';
 import path from 'path';
 import { mkdtemp, rm, readFile, writeFile } from 'fs/promises';
@@ -173,3 +173,160 @@ describe('project-config runtime', () => {
     }
   });
 });
+
+describe('project-config loop reconciliation', () => {
+  const loop = (name, overrides = {}) => ({
+    scope: 'project',
+    filePath: `/repo/.agents/loops/${name}.md`,
+    definition: {
+      name,
+      enabled: true,
+      schedule: { kind: 'cron', cron: '0 9 * * *', timezone: 'UTC' },
+      execution: {
+        prompt: `Loop prompt for ${name}`,
+        providerID: 'openai',
+        modelID: 'gpt-4.1',
+      },
+      ...overrides,
+    },
+  });
+
+  it('creates tasks for discovered loops with deterministic ids', async () => {
+    const { runtime, cleanup } = await createRuntime();
+    try {
+      const tasks = await runtime.reconcileLoopTasks('project-test', [
+        loop('daily-digest'),
+        loop('weekly-report'),
+      ]);
+
+      expect(tasks).toHaveLength(2);
+      const digest = tasks.find((task) => task.name === 'daily-digest');
+      expect(digest.id).toBe('loop:project:daily-digest');
+      expect(digest.schedule.cron).toBe('0 9 * * *');
+      expect(digest.execution.providerID).toBe('openai');
+      expect(digest.loopFile).toBe('/repo/.agents/loops/daily-digest.md');
+
+      const reloaded = await runtime.listScheduledTasks('project-test');
+      expect(reloaded).toHaveLength(2);
+      expect(reloaded[0].state.createdAt).toBeGreaterThan(0);
+    } finally {
+      await cleanup();
+    }
+  });
+
+  it('adopts an existing task by name, preserving id and state, and persists state across reconciles', async () => {
+    const { runtime, cleanup } = await createRuntime();
+    try {
+      const created = await runtime.upsertScheduledTask('project-test', {
+        name: 'daily-digest',
+        enabled: true,
+        schedule: { kind: 'daily', time: '09:30', timezone: 'UTC' },
+        execution: { prompt: 'JSON prompt', providerID: 'openai', modelID: 'gpt-4.1' },
+      });
+
+      const first = await runtime.reconcileLoopTasks('project-test', [loop('daily-digest')]);
+      const adopted = first.find((task) => task.id === created.task.id);
+      expect(adopted).toBeDefined();
+      expect(adopted.id).toBe(created.task.id);
+      expect(adopted.name).toBe('daily-digest');
+      expect(adopted.schedule.kind).toBe('cron');
+      expect(adopted.schedule.cron).toBe('0 9 * * *');
+      expect(adopted.execution.prompt).toBe('Loop prompt for daily-digest');
+      expect(adopted.loopFile).toBe('/repo/.agents/loops/daily-digest.md');
+
+      const state = adopted.state;
+      await runtime.updateScheduledTaskState('project-test', adopted.id, {
+        nextRunAt: 123456,
+        lastRunAt: 111,
+        lastStatus: 'success',
+      });
+
+      const second = await runtime.reconcileLoopTasks('project-test', [loop('daily-digest')]);
+      const again = second.find((task) => task.id === created.task.id);
+      expect(again.id).toBe(created.task.id);
+      expect(again.state.nextRunAt).toBe(123456);
+      expect(again.state.lastRunAt).toBe(111);
+      expect(again.state.lastStatus).toBe('success');
+      expect(again.loopFile).toBe('/repo/.agents/loops/daily-digest.md');
+    } finally {
+      await cleanup();
+    }
+  });
+
+  it('unschedules a loop-sourced task when its file is removed', async () => {
+    const { runtime, cleanup } = await createRuntime();
+    try {
+      await runtime.reconcileLoopTasks('project-test', [loop('daily-digest')]);
+      const tasks = await runtime.reconcileLoopTasks('project-test', []);
+
+      expect(tasks).toHaveLength(0);
+      expect(await runtime.listScheduledTasks('project-test')).toHaveLength(0);
+    } finally {
+      await cleanup();
+    }
+  });
+
+  it('leaves JSON-configured tasks untouched when no loop matches', async () => {
+    const { runtime, cleanup } = await createRuntime();
+    try {
+      const created = await runtime.upsertScheduledTask('project-test', {
+        name: 'json-only',
+        enabled: true,
+        schedule: { kind: 'daily', time: '08:00', timezone: 'UTC' },
+        execution: { prompt: 'JSON prompt', providerID: 'openai', modelID: 'gpt-4.1' },
+      });
+
+      const tasks = await runtime.reconcileLoopTasks('project-test', [loop('loop-only')]);
+
+      expect(tasks).toHaveLength(2);
+      expect(tasks.find((task) => task.id === created.task.id)).toBeDefined();
+      expect(tasks.find((task) => task.name === 'loop-only')).toBeDefined();
+    } finally {
+      await cleanup();
+    }
+  });
+
+  it('does not remove a JSON task that merely shares a loop name after the loop is gone... keeps it when never adopted', async () => {
+    // A JSON task that was never driven by a loop file (no loopFile marker)
+    // must survive reconciles even when a loop with the same name existed
+    // only in a previous reconcile round — but once a loop adopted it, the
+    // file is authoritative and removing the file unschedules the task.
+    const { runtime, cleanup } = await createRuntime();
+    try {
+      const created = await runtime.upsertScheduledTask('project-test', {
+        name: 'daily-digest',
+        enabled: true,
+        schedule: { kind: 'daily', time: '09:30', timezone: 'UTC' },
+        execution: { prompt: 'JSON prompt', providerID: 'openai', modelID: 'gpt-4.1' },
+      });
+
+      // First reconcile adopts the task (loopFile marker set).
+      await runtime.reconcileLoopTasks('project-test', [loop('daily-digest')]);
+      // Loop file removed -> task unscheduled.
+      const afterRemoval = await runtime.reconcileLoopTasks('project-test', []);
+      expect(afterRemoval.find((task) => task.id === created.task.id)).toBeUndefined();
+    } finally {
+      await cleanup();
+    }
+  });
+
+  it('skips invalid loop definitions without blocking valid ones', async () => {
+    const { runtime, cleanup } = await createRuntime();
+    try {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+      try {
+        const tasks = await runtime.reconcileLoopTasks('project-test', [
+          loop('bad-loop', { schedule: { kind: 'cron', cron: 'not a cron', timezone: 'UTC' } }),
+          loop('good-loop'),
+        ]);
+
+        expect(tasks.map((task) => task.name)).toEqual(['good-loop']);
+        expect(warn).toHaveBeenCalled();
+      } finally {
+        warn.mockRestore();
+      }
+    } finally {
+      await cleanup();
+    }
+  });
+});
diff --git a/packages/web/server/lib/scheduled-tasks/DOCUMENTATION.md b/packages/web/server/lib/scheduled-tasks/DOCUMENTATION.md
index 2fc61770..16206a82 100644
--- a/packages/web/server/lib/scheduled-tasks/DOCUMENTATION.md
+++ b/packages/web/server/lib/scheduled-tasks/DOCUMENTATION.md
@@ -5,7 +5,8 @@ Server-owned scheduled task runtime and routes for OpenChamber-only automation.
 ## Scope
 
 - Per-project scheduled task persistence is owned by `packages/web/server/lib/projects/project-config.js`.
-- Runtime orchestration and execution is owned by this module.
+- Markdown loop discovery/parsing is owned by `packages/web/server/lib/scheduled-tasks/loops.js`.
+- Runtime orchestration and execution is owned by `packages/web/server/lib/scheduled-tasks/runtime.js`.
 - This module is OpenChamber feature logic; it is intentionally separate from OpenCode proxy/runtime internals.
 
 ## Files
@@ -17,11 +18,74 @@ Server-owned scheduled task runtime and routes for OpenChamber-only automation.
   - Session create + prompt_async execution
   - Emits OpenChamber task-run events
 
+- `packages/web/server/lib/scheduled-tasks/loops.js`
+  - Discovery of `.agents/loops/*.md` (project scope, ancestors up to the worktree root) and `~/.agents/loops/*.md` (user scope)
+  - Frontmatter parsing into scheduled-task definitions
+  - `syncProject` reconciles discovered loops with the persisted task list on every project sync (startup, task save/delete)
+
 - `packages/web/server/lib/scheduled-tasks/routes.js`
   - Scheduled task CRUD endpoints
   - Manual run endpoint
   - OpenChamber events SSE stream endpoint
 
+## Loop file format
+
+Portable, git-commit-able scheduled-task definitions:
+
+```markdown
+---
+name: daily-digest
+schedule: "0 9 * * *"
+enabled: true
+model: anthropic/claude-sonnet-4-5
+agent: plan
+timezone: Europe/Kyiv
+---
+Summarize repository changes since yesterday.
+```
+
+Field mapping (model: `packages/ui/src/lib/scheduledTasksApi.ts`):
+
+| Frontmatter | Task field |
+|---|---|
+| `name` | `name` (required) |
+| `schedule` | `schedule.kind: "cron"` + `schedule.cron` (required, cron-only in the portable format) |
+| `enabled` | `enabled` (default `true`) |
+| `model` | split on the first `/` into `execution.providerID` / `execution.modelID` (required) |
+| `agent` | `execution.agent` (optional) |
+| `timezone` | `schedule.timezone` (optional, IANA; defaults to the server zone) |
+| body | `execution.prompt` (required) |
+
+`thinking_level` and `goalEnabled`/`goalTokenBudget` are not part of the portable
+format (UI/JSON-only today); `daily`/`weekly`/`once` schedules remain UI/JSON-only.
+Runtime state (`lastRunAt`, `nextRunAt`, `lastStatus`, `lastError`, `lastSessionId`,
+`lastDurationMs`) is never written to the markdown file — it continues to live in
+the project config state store.
+
+## Loop reconciliation rules
+
+`projectConfigRuntime.reconcileLoopTasks(projectID, loops)` runs inside the
+project write lock on every `syncProject` when the project path is known:
+
+- **Identity is the task name.** A loop whose name matches an existing task
+  takes that task over: its schedule/execution/enabled are overwritten from the
+  file while the task's `id` and runtime `state` are preserved (markdown wins
+  on conflict with JSON-configured tasks).
+- **Deletion.** A task carrying the `loopFile` marker whose loop file is no
+  longer discovered (removed or renamed) is unscheduled (removed from the
+  config). The marker is persisted in the config file, so removal is detected
+  across restarts. JSON-configured tasks without the marker are never removed.
+- **Creation.** Loops without a matching task are created under a deterministic
+  `loop:<scope>:<name>` id so runtime state survives restarts.
+- **Scope precedence.** Project-scope loops shadow user-scope loops with the
+  same name; among project files the nearest ancestor wins.
+- **Malformed files** (missing `name`/`schedule`/`model`/body, invalid cron,
+  unreadable) are skipped with a warning and never block valid loops in the
+  same or other scopes.
+- **UI edits** to a loop-sourced task are preserved in the config but the loop
+  file remains authoritative: the next reconciliation re-applies the file's
+  definition (including `enabled`). Use `enabled: false` in the file to disable.
+
 ## Public exports (runtime.js)
 
 - `createScheduledTasksRuntime(dependencies)`
diff --git a/packages/web/server/lib/scheduled-tasks/loops.js b/packages/web/server/lib/scheduled-tasks/loops.js
new file mode 100644
index 00000000..2dbcf4c2
--- /dev/null
+++ b/packages/web/server/lib/scheduled-tasks/loops.js
@@ -0,0 +1,189 @@
+/**
+ * Markdown loops — portable scheduled-task definitions.
+ *
+ * Loops are git-commit-able markdown files with YAML frontmatter, discovered
+ * from `.agents/loops/*.md` (project scope, including ancestor directories up
+ * to the worktree root) and `~/.agents/loops/*.md` (user scope), mirroring the
+ * skills discovery pattern (`packages/web/server/lib/opencode/skills.js`).
+ *
+ * File format:
+ *
+ *   ---
+ *   name: daily-digest
+ *   schedule: "0 9 * * *"
+ *   enabled: true
+ *   model: anthropic/claude-sonnet-4-5
+ *   agent: plan
+ *   timezone: Europe/Kyiv
+ *   ---
+ *   Summarize repository changes since yesterday and post the digest.
+ *
+ * Field mapping (see packages/ui/src/lib/scheduledTasksApi.ts):
+ *   name     -> task.name
+ *   schedule -> task.schedule.kind "cron" + task.schedule.cron
+ *   enabled  -> task.enabled (default true)
+ *   model    -> split into task.execution.providerID / task.execution.modelID
+ *   agent    -> task.execution.agent (optional)
+ *   timezone -> task.schedule.timezone (optional, defaults to the server zone)
+ *   body     -> task.execution.prompt
+ *
+ * `thinking_level` and `goalEnabled`/`goalTokenBudget` are not part of the
+ * portable format (they are UI-only today); editing them in the file has no
+ * effect and they remain JSON/UI-only.
+ *
+ * Runtime state (lastRunAt, nextRunAt, lastStatus, ...) is never written to
+ * the markdown file; it continues to live in the project config/state store.
+ */
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { parseMdFile, getAncestors, findWorktreeRoot } from '../opencode/shared.js';
+
+const LOOP_DIR_NAME = 'loops';
+const USER_LOOP_ROOT = () => path.join(os.homedir(), '.agents', LOOP_DIR_NAME);
+
+const asNonEmptyString = (value) => {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+};
+
+/**
+ * Split a `provider/model` string into its two parts. Splits on the first `/`
+ * so model ids containing a slash (e.g. `openai/gpt-5`) still resolve.
+ */
+const splitProviderModel = (value) => {
+  const raw = asNonEmptyString(value);
+  if (!raw) {
+    return null;
+  }
+  const separator = raw.indexOf('/');
+  if (separator <= 0 || separator === raw.length - 1) {
+    return null;
+  }
+  return {
+    providerId: raw.slice(0, separator).trim(),
+    modelId: raw.slice(separator + 1).trim(),
+  };
+};
+
+/**
+ * Parse one loop markdown file into a scheduled-task definition, or return
+ * null when the file is malformed. Malformed files are skipped with a warning
+ * and never prevent valid files from loading.
+ */
+export const parseLoopDefinition = (filePath) => {
+  let parsed;
+  try {
+    parsed = parseMdFile(filePath);
+  } catch (error) {
+    console.warn(`[loops] skipped malformed loop file ${filePath}:`, error?.message ?? error);
+    return null;
+  }
+
+  const frontmatter = parsed.frontmatter && typeof parsed.frontmatter === 'object'
+    ? parsed.frontmatter
+    : {};
+  const name = asNonEmptyString(frontmatter.name);
+  if (!name) {
+    console.warn(`[loops] skipped ${filePath}: frontmatter "name" is required`);
+    return null;
+  }
+
+  const cron = asNonEmptyString(frontmatter.schedule);
+  if (!cron) {
+    console.warn(`[loops] skipped ${filePath}: frontmatter "schedule" (cron expression) is required`);
+    return null;
+  }
+
+  const prompt = asNonEmptyString(parsed.body);
+  if (!prompt) {
+    console.warn(`[loops] skipped ${filePath}: markdown body (the execution prompt) is required`);
+    return null;
+  }
+
+  const providerModel = splitProviderModel(frontmatter.model);
+  if (!providerModel) {
+    console.warn(`[loops] skipped ${filePath}: frontmatter "model" must be "provider/model"`);
+    return null;
+  }
+
+  const timezone = asNonEmptyString(frontmatter.timezone);
+  const agent = asNonEmptyString(frontmatter.agent);
+
+  return {
+    name,
+    enabled: typeof frontmatter.enabled === 'boolean' ? frontmatter.enabled : true,
+    schedule: {
+      kind: 'cron',
+      cron,
+      ...(timezone ? { timezone } : {}),
+    },
+    execution: {
+      prompt,
+      providerID: providerModel.providerId,
+      modelID: providerModel.modelId,
+      ...(agent ? { agent } : {}),
+    },
+  };
+};
+
+const walkLoopMdFiles = (rootDir) => {
+  if (!rootDir || !fs.existsSync(rootDir)) {
+    return [];
+  }
+  try {
+    return fs.readdirSync(rootDir, { withFileTypes: true })
+      .filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
+      .map((entry) => path.join(rootDir, entry.name))
+      .sort();
+  } catch {
+    return [];
+  }
+};
+
+/**
+ * Discover loop files for a project: `~/.agents/loops/*.md` (user scope) plus
+ * `.agents/loops/*.md` in every ancestor of the project path up to the
+ * worktree root (project scope).
+ */
+export const discoverLoopFiles = (projectPath) => {
+  const files = [];
+  for (const filePath of walkLoopMdFiles(USER_LOOP_ROOT())) {
+    files.push({ filePath, scope: 'user' });
+  }
+  if (projectPath) {
+    const worktreeRoot = findWorktreeRoot(projectPath) || path.resolve(projectPath);
+    for (const ancestor of getAncestors(projectPath, worktreeRoot)) {
+      const root = path.join(ancestor, '.agents', LOOP_DIR_NAME);
+      for (const filePath of walkLoopMdFiles(root)) {
+        files.push({ filePath, scope: 'project' });
+      }
+    }
+  }
+  return files;
+};
+
+/**
+ * Discover and parse all loops for a project. Project-scope loops shadow
+ * user-scope loops with the same name; among project files the nearest
+ * ancestor wins. Malformed files are skipped with a warning.
+ */
+export const discoverLoops = (projectPath) => {
+  const byName = new Map();
+  for (const { filePath, scope } of discoverLoopFiles(projectPath)) {
+    const definition = parseLoopDefinition(filePath);
+    if (!definition) {
+      continue;
+    }
+    const existing = byName.get(definition.name);
+    if (existing && (existing.scope === 'project' || scope === 'user')) {
+      continue;
+    }
+    byName.set(definition.name, { scope, filePath, definition });
+  }
+  return [...byName.values()];
+};
diff --git a/packages/web/server/lib/scheduled-tasks/loops.test.js b/packages/web/server/lib/scheduled-tasks/loops.test.js
new file mode 100644
index 00000000..ac204392
--- /dev/null
+++ b/packages/web/server/lib/scheduled-tasks/loops.test.js
@@ -0,0 +1,335 @@
+import { describe, expect, it, vi } from 'vitest';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { mkdtemp, rm, writeFile, mkdir } from 'fs/promises';
+import { parseLoopDefinition, discoverLoops, discoverLoopFiles } from './loops.js';
+
+const createProject = async () => {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), 'oc-loops-'));
+  const projectPath = path.join(tempRoot, 'repo');
+  await mkdir(projectPath, { recursive: true });
+  await mkdir(path.join(projectPath, '.git'), { recursive: true });
+  return {
+    projectPath,
+    cleanup: async () => {
+      await rm(tempRoot, { recursive: true, force: true });
+    },
+  };
+};
+
+const writeLoop = async (projectPath, fileName, content) => {
+  const dir = path.join(projectPath, '.agents', 'loops');
+  await mkdir(dir, { recursive: true });
+  await writeFile(path.join(dir, fileName), content, 'utf8');
+};
+
+describe('parseLoopDefinition', () => {
+  it('maps frontmatter and body to the scheduled-task definition shape', async () => {
+    const { projectPath, cleanup } = await createProject();
+    try {
+      await writeLoop(projectPath, 'digest.md', `---
+name: daily-digest
+schedule: "0 9 * * *"
+enabled: true
+model: anthropic/claude-sonnet-4-5
+agent: plan
+timezone: Europe/Kyiv
+---
+Summarize repository changes since yesterday.
+`);
+
+      const definition = parseLoopDefinition(path.join(projectPath, '.agents', 'loops', 'digest.md'));
+
+      expect(definition).toEqual({
+        name: 'daily-digest',
+        enabled: true,
+        schedule: { kind: 'cron', cron: '0 9 * * *', timezone: 'Europe/Kyiv' },
+        execution: {
+          prompt: 'Summarize repository changes since yesterday.',
+          providerID: 'anthropic',
+          modelID: 'claude-sonnet-4-5',
+          agent: 'plan',
+        },
+      });
+    } finally {
+      await cleanup();
+    }
+  });
+
+  it('splits model ids containing a slash on the first separator', async () => {
+    const { projectPath, cleanup } = await createProject();
+    try {
+      const filePath = path.join(projectPath, 'loop.md');
+      await writeFile(filePath, `---
+name: nested-model
+schedule: "0 8 * * 1"
+model: openai/gpt-5
+---
+Run weekly checks.
+`, 'utf8');
+
+      const definition = parseLoopDefinition(filePath);
+
+      expect(definition.execution.providerID).toBe('openai');
+      expect(definition.execution.modelID).toBe('gpt-5');
+      expect(definition.enabled).toBe(true);
+    } finally {
+      await cleanup();
+    }
+  });
+
+  it('defaults enabled to true and omits optional fields', async () => {
+    const { projectPath, cleanup } = await createProject();
+    try {
+      const filePath = path.join(projectPath, 'loop.md');
+      await writeFile(filePath, `---
+name: minimal
+schedule: "*/30 * * * *"
+model: openai/gpt-5
+enabled: false
+---
+Run every half hour.
+`, 'utf8');
+
+      const definition = parseLoopDefinition(filePath);
+
+      expect(definition.enabled).toBe(false);
+      expect(definition.schedule).toEqual({ kind: 'cron', cron: '*/30 * * * *' });
+      expect(definition.execution.agent).toBeUndefined();
+    } finally {
+      await cleanup();
+    }
+  });
+
+  it('returns null for files missing required frontmatter fields', async () => {
+    const { projectPath, cleanup } = await createProject();
+    try {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+      try {
+        const noName = path.join(projectPath, 'noname.md');
+        await writeFile(noName, `---
+schedule: "0 9 * * *"
+model: openai/gpt-5
+---
+Prompt only.
+`, 'utf8');
+        expect(parseLoopDefinition(noName)).toBeNull();
+
+        const noSchedule = path.join(projectPath, 'noschedule.md');
+        await writeFile(noSchedule, `---
+name: no-schedule
+model: openai/gpt-5
+---
+Prompt only.
+`, 'utf8');
+        expect(parseLoopDefinition(noSchedule)).toBeNull();
+
+        const noModel = path.join(projectPath, 'nomodel.md');
+        await writeFile(noModel, `---
+name: no-model
+schedule: "0 9 * * *"
+---
+Prompt only.
+`, 'utf8');
+        expect(parseLoopDefinition(noModel)).toBeNull();
+
+        const malformed = path.join(projectPath, 'malformed.md');
+        await writeFile(malformed, 'not a markdown frontmatter file at all', 'utf8');
+        expect(parseLoopDefinition(malformed)).toBeNull();
+      } finally {
+        warn.mockRestore();
+      }
+    } finally {
+      await cleanup();
+    }
+  });
+
+  it('treats a missing body as an invalid loop', async () => {
+    const { projectPath, cleanup } = await createProject();
+    try {
+      const filePath = path.join(projectPath, 'empty-body.md');
+      await writeFile(filePath, `---
+name: empty-body
+schedule: "0 9 * * *"
+model: openai/gpt-5
+---
+`, 'utf8');
+
+      expect(parseLoopDefinition(filePath)).toBeNull();
+    } finally {
+      await cleanup();
+    }
+  });
+});
+
+describe('discoverLoops', () => {
+  it('discovers project loops and parses them', async () => {
+    const { projectPath, cleanup } = await createProject();
+    try {
+      await writeLoop(projectPath, 'digest.md', `---
+name: daily-digest
+schedule: "0 9 * * *"
+model: openai/gpt-5
+---
+Summarize.
+`);
+
+      const loops = discoverLoops(projectPath);
+
+      expect(loops).toHaveLength(1);
+      expect(loops[0].scope).toBe('project');
+      expect(loops[0].definition.name).toBe('daily-digest');
+      expect(loops[0].filePath.endsWith(path.join('.agents', 'loops', 'digest.md'))).toBe(true);
+    } finally {
+      await cleanup();
+    }
+  });
+
+  it('scans ancestor directories up to the worktree root', async () => {
+    const { projectPath, cleanup } = await createProject();
+    try {
+      // Worktree root contains the loop; the project directory is nested.
+      const nested = path.join(projectPath, 'src', 'nested');
+      await mkdir(nested, { recursive: true });
+      await writeLoop(projectPath, 'root-loop.md', `---
+name: root-loop
+schedule: "0 9 * * *"
+model: openai/gpt-5
+---
+From the root.
+`);
+
+      const loops = discoverLoops(nested);
+
+      expect(loops.map((loop) => loop.definition.name)).toEqual(['root-loop']);
+      expect(loops[0].scope).toBe('project');
+    } finally {
+      await cleanup();
+    }
+  });
+
+  it('discovers user-scope loops from ~/.agents/loops', async () => {
+    const { projectPath, cleanup } = await createProject();
+    const home = await mkdtemp(path.join(os.tmpdir(), 'oc-loops-home-'));
+    const userDir = path.join(home, '.agents', 'loops');
+    await mkdir(userDir, { recursive: true });
+    await writeFile(path.join(userDir, 'user-loop.md'), `---
+name: user-loop
+schedule: "0 7 * * *"
+model: openai/gpt-5
+---
+User scope.
+`, 'utf8');
+    const originalHome = os.homedir;
+    vi.spyOn(os, 'homedir').mockReturnValue(home);
+
+    try {
+      const loops = discoverLoops(projectPath);
+
+      expect(loops.map((loop) => loop.definition.name)).toEqual(['user-loop']);
+      expect(loops[0].scope).toBe('user');
+    } finally {
+      os.homedir = originalHome;
+      await rm(home, { recursive: true, force: true });
+      await cleanup();
+    }
+  });
+
+  it('lets project scope shadow user scope on name collision', async () => {
+    const { projectPath, cleanup } = await createProject();
+    const home = await mkdtemp(path.join(os.tmpdir(), 'oc-loops-home-'));
+    const userDir = path.join(home, '.agents', 'loops');
+    await mkdir(userDir, { recursive: true });
+    await writeFile(path.join(userDir, 'same-name.md'), `---
+name: shared
+schedule: "0 7 * * *"
+model: openai/gpt-5
+---
+User version.
+`, 'utf8');
+    await writeLoop(projectPath, 'same-name.md', `---
+name: shared
+schedule: "0 8 * * *"
+model: anthropic/claude-sonnet-4-5
+---
+Project version.
+`);
+    const originalHome = os.homedir;
+    vi.spyOn(os, 'homedir').mockReturnValue(home);
+
+    try {
+      const loops = discoverLoops(projectPath);
+
+      expect(loops).toHaveLength(1);
+      expect(loops[0].scope).toBe('project');
+      expect(loops[0].definition.execution.providerID).toBe('anthropic');
+      expect(loops[0].definition.schedule.cron).toBe('0 8 * * *');
+    } finally {
+      os.homedir = originalHome;
+      await rm(home, { recursive: true, force: true });
+      await cleanup();
+    }
+  });
+
+  it('skips malformed files without blocking valid ones', async () => {
+    const { projectPath, cleanup } = await createProject();
+    try {
+      await writeLoop(projectPath, 'bad.md', `---
+name: bad
+schedule: "0 9 * * *"
+---
+No model.
+`);
+      await writeLoop(projectPath, 'good.md', `---
+name: good
+schedule: "0 9 * * *"
+model: openai/gpt-5
+---
+Valid.
+`);
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+      try {
+        const loops = discoverLoops(projectPath);
+
+        expect(loops.map((loop) => loop.definition.name)).toEqual(['good']);
+        expect(warn).toHaveBeenCalled();
+      } finally {
+        warn.mockRestore();
+      }
+    } finally {
+      await cleanup();
+    }
+  });
+
+  it('returns an empty list when nothing exists', async () => {
+    const { projectPath, cleanup } = await createProject();
+    try {
+      expect(discoverLoops(projectPath)).toEqual([]);
+    } finally {
+      await cleanup();
+    }
+  });
+
+  it('lists raw loop files per scope without parsing', async () => {
+    const { projectPath, cleanup } = await createProject();
+    try {
+      await writeLoop(projectPath, 'one.md', `---
+name: one
+schedule: "0 9 * * *"
+model: openai/gpt-5
+---
+One.
+`);
+      await writeFile(path.join(projectPath, 'not-a-loop.txt'), 'ignore me', 'utf8');
+
+      const files = discoverLoopFiles(projectPath);
+
+      expect(files).toHaveLength(1);
+      expect(files[0].scope).toBe('project');
+      expect(files[0].filePath.endsWith(path.join('.agents', 'loops', 'one.md'))).toBe(true);
+    } finally {
+      await cleanup();
+    }
+  });
+});
diff --git a/packages/web/server/lib/scheduled-tasks/runtime.js b/packages/web/server/lib/scheduled-tasks/runtime.js
index 5b1cffc7..62015b95 100644
--- a/packages/web/server/lib/scheduled-tasks/runtime.js
+++ b/packages/web/server/lib/scheduled-tasks/runtime.js
@@ -3,6 +3,7 @@ import { DateTime } from 'luxon';
 import parser from 'cron-parser';
 import { expandSnippets } from '../opencode/snippets.js';
 import { buildGoalIntroText, createSessionGoal } from '../session-goal/create.js';
+import { discoverLoops } from './loops.js';
 
 const DEFAULT_GLOBAL_CONCURRENCY = 4;
 const DEFAULT_PROJECT_CONCURRENCY = 2;
@@ -382,8 +383,19 @@ export const createScheduledTasksRuntime = (deps) => {
 
   const syncProject = async (projectID) => {
     await ensureProjectPath(projectID);
+    const projectPath = projectPathByID.get(projectID) || null;
+
+    let tasks;
+    if (projectPath) {
+      // Reconcile `.agents/loops` definitions with the persisted task list:
+      // loop files are authoritative while present, removed files unschedule
+      // their task, and runtime state is preserved (see loops.js).
+      const loops = await discoverLoops(projectPath);
+      tasks = await projectConfigRuntime.reconcileLoopTasks(projectID, loops);
+    } else {
+      tasks = await projectConfigRuntime.listScheduledTasks(projectID);
+    }
 
-    const tasks = await projectConfigRuntime.listScheduledTasks(projectID);
     setProjectTasks(projectID, tasks);
 
     for (const task of tasks) {

From e3202df03799ac2fd071192a977b2e5d7cbb2e7f Mon Sep 17 00:00:00 2001
From: Serhii Dziupin <serkraser@gmail.com>
Date: Wed, 5 Aug 2026 14:15:03 +0300
Subject: [PATCH 27/57] fix(sync): finalize tool parts orphaned by an
 interrupted turn after settlement
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When a managed OpenCode process dies mid-turn (crash, health-check
restart), the persisted turn never settles: the trailing assistant
message has no time.completed and its tool parts stay pending/running
forever — the server never finalizes them (anomalyco/opencode#19023).
The existing settle-triggered tail refresh refetches the same stale
records, so the UI kept running tool timers and working styling
indefinitely (#2577).

Now, when a session is authoritatively settled (session.idle/
session.error event, or an authoritative status snapshot lowering a
previously busy session) and the trailing assistant message is still
unfinished with active tool parts and no pending question/permission,
the orphaned parts are finalized locally as error/"Interrupted" with
an end time — the same shape OpenCode itself writes for cancelled
tools. The mark is gated on an explicit idle status (absent status is
"unknown", never judged), never applies while busy (including
question/permission waits), and a later terminal event or refresh
supersedes it while a stale running refresh cannot regress it (the
reducer and materializer already preserve final statuses).

Fixes #2577
---
 packages/ui/src/sync/DOCUMENTATION.md         |   2 +
 .../__tests__/interrupted-turn-tools.test.ts  | 152 ++++++++++++++++++
 .../sync/__tests__/materialization.test.ts    |  33 ++++
 packages/ui/src/sync/sync-context.tsx         | 100 ++++++++++++
 4 files changed, 287 insertions(+)
 create mode 100644 packages/ui/src/sync/__tests__/interrupted-turn-tools.test.ts

diff --git a/packages/ui/src/sync/DOCUMENTATION.md b/packages/ui/src/sync/DOCUMENTATION.md
index 5699fc93..420004a2 100644
--- a/packages/ui/src/sync/DOCUMENTATION.md
+++ b/packages/ui/src/sync/DOCUMENTATION.md
@@ -204,6 +204,8 @@ Incomplete-session materialization is deduplicated by runtime, directory, and se
 
 When `session.idle` or `session.error` settles a session but the trailing assistant message still contains a `pending` or `running` tool, sync refreshes that session tail. This narrowly reconciles a missed terminal tool-part event without refetching normally completed turns or stale tools from older turns. A stale refresh or delayed part event cannot regress a locally observed terminal tool to an active status.
 
+When a session is authoritatively settled — `session.idle`/`session.error` event, or an authoritative status snapshot that lowers a previously busy session — and the trailing assistant message is still *unfinished* (`time.completed` missing) with active tool parts and no pending question/permission, the turn is treated as interrupted (managed OpenCode process died mid-turn; the server never finalizes the parts, see openchamber#2577 / anomalyco/opencode#19023). The active parts are finalized locally as `error`/`Interrupted` with an end time, so tool timers stop and cards render the error state. The mark is gated on an explicit idle status (absent status is "unknown", never judged), never applies while the session is busy (including question/permission waits), and a later terminal event or refresh supersedes it while a stale `running` refresh cannot regress it.
+
 Directory stores also own session-keyed sidecar notification channels for permissions and message materialization. High-frequency realtime part events annotate the exact session/message before committing, so visible records, user history, renderability, and sidebar permission rows are not notified by unrelated sessions. Structural message replacements notify only changed subscribed session buckets; unannotated bulk part replacement conservatively resets active message subscribers so bootstrap, pagination, rollback, and legacy writers cannot leave stale projections.
 
 Message sidecar consumers also filter targeted updates by purpose before notifying React. Suspended live-tail text/reasoning changes do not rebuild visible message records, but structural Task session identity changes bypass suspension so a parent can link a newly created subagent immediately. Assistant-only part changes do not rebuild user input history, and targeted updates that preserve authoritative part buckets do not recheck a session that is already renderable. Message replacements, removed final part buckets, and conservative resets always notify.
diff --git a/packages/ui/src/sync/__tests__/interrupted-turn-tools.test.ts b/packages/ui/src/sync/__tests__/interrupted-turn-tools.test.ts
new file mode 100644
index 00000000..60968ef7
--- /dev/null
+++ b/packages/ui/src/sync/__tests__/interrupted-turn-tools.test.ts
@@ -0,0 +1,152 @@
+/**
+ * Tests for interrupted-turn reconciliation (#2577): when a managed OpenCode
+ * process dies mid-turn, the persisted turn never settles — the trailing
+ * assistant message has no time.completed and its tool parts stay running.
+ * Once the session is authoritatively settled, `interruptedTurnToolParts`
+ * finalizes the orphaned parts locally.
+ */
+import { describe, expect, test } from "bun:test"
+import type { Message, Part } from "@opencode-ai/sdk/v2/client"
+import { interruptedTurnToolParts } from "../sync-context"
+import type { DirectoryStore } from "../child-store"
+import { INITIAL_STATE } from "../types"
+
+function state(overrides: Partial<DirectoryStore> = {}): DirectoryStore {
+  return {
+    ...INITIAL_STATE,
+    session_status: {},
+    message: {},
+    part: {},
+    question: {},
+    permission: {},
+    ...overrides,
+  } as unknown as DirectoryStore
+}
+
+function runningTool(id: string, messageID: string, start = 1000): Part {
+  return {
+    id,
+    messageID,
+    sessionID: "ses_1",
+    type: "tool",
+    tool: "bash",
+    state: { status: "running", time: { start }, input: {} },
+  } as unknown as Part
+}
+
+function completedTool(id: string, messageID: string): Part {
+  return {
+    id,
+    messageID,
+    sessionID: "ses_1",
+    type: "tool",
+    tool: "bash",
+    state: { status: "completed", time: { start: 1000, end: 2000 }, input: {} },
+  } as unknown as Part
+}
+
+function pendingTool(id: string, messageID: string): Part {
+  return {
+    id,
+    messageID,
+    sessionID: "ses_1",
+    type: "tool",
+    tool: "bash",
+    state: { status: "pending", time: { start: 1000 }, input: {} },
+  } as unknown as Part
+}
+
+function unfinishedAssistantMessage(id: string): Message {
+  return { id, sessionID: "ses_1", role: "assistant", parentID: "", modelID: "", providerID: "", mode: "primary", system: "", agent: "", model: "", time: { created: 10 } } as unknown as Message
+}
+
+function finishedAssistantMessage(id: string): Message {
+  return { id, sessionID: "ses_1", role: "assistant", parentID: "", modelID: "", providerID: "", mode: "primary", system: "", agent: "", model: "", time: { created: 10, completed: 2000 } } as unknown as Message
+}
+
+describe("interruptedTurnToolParts (#2577)", () => {
+  test("settled session with unfinished message and running tool finalizes the part", () => {
+    const store = state({
+      session_status: { ses_1: { type: "idle" } },
+      message: { ses_1: [unfinishedAssistantMessage("msg_1")] },
+      part: { msg_1: [runningTool("tool_1", "msg_1")] },
+    })
+
+    const result = interruptedTurnToolParts(store, "ses_1", 5000)
+    expect(result).not.toBeNull()
+    const part = result!.parts[0] as { state: { status: string; error: string; time: { end: number } } }
+    expect(part.state.status).toBe("error")
+    expect(part.state.error).toBe("Interrupted")
+    expect(part.state.time.end).toBe(5000)
+  })
+
+  test("busy session is never marked (live work)", () => {
+    const store = state({
+      session_status: { ses_1: { type: "busy" } },
+      message: { ses_1: [unfinishedAssistantMessage("msg_1")] },
+      part: { msg_1: [runningTool("tool_1", "msg_1")] },
+    })
+    expect(interruptedTurnToolParts(store, "ses_1")).toBeNull()
+  })
+
+  test("absent status is unknown, not settled — never marked", () => {
+    const store = state({
+      message: { ses_1: [unfinishedAssistantMessage("msg_1")] },
+      part: { msg_1: [runningTool("tool_1", "msg_1")] },
+    })
+    expect(interruptedTurnToolParts(store, "ses_1")).toBeNull()
+  })
+
+  test("finished message is not an interruption (tail refresh reconciles it)", () => {
+    const store = state({
+      session_status: { ses_1: { type: "idle" } },
+      message: { ses_1: [finishedAssistantMessage("msg_1")] },
+      part: { msg_1: [runningTool("tool_1", "msg_1")] },
+    })
+    expect(interruptedTurnToolParts(store, "ses_1")).toBeNull()
+  })
+
+  test("pending question means the turn is waiting for input, not interrupted", () => {
+    const store = state({
+      session_status: { ses_1: { type: "idle" } },
+      message: { ses_1: [unfinishedAssistantMessage("msg_1")] },
+      part: { msg_1: [runningTool("tool_1", "msg_1")] },
+      question: { ses_1: [{ id: "q_1", sessionID: "ses_1", questions: [{ question: "?", header: "h", options: [{ label: "a", description: "" }] }] }] },
+    })
+    expect(interruptedTurnToolParts(store, "ses_1")).toBeNull()
+  })
+
+  test("pending permission means the turn is waiting for input, not interrupted", () => {
+    const store = state({
+      session_status: { ses_1: { type: "idle" } },
+      message: { ses_1: [unfinishedAssistantMessage("msg_1")] },
+      part: { msg_1: [runningTool("tool_1", "msg_1")] },
+      permission: { ses_1: [{ id: "p_1", sessionID: "ses_1", permission: "bash", patterns: [], metadata: {}, always: [] }] },
+    })
+    expect(interruptedTurnToolParts(store, "ses_1")).toBeNull()
+  })
+
+  test("only active parts are finalized; completed parts are untouched", () => {
+    const store = state({
+      session_status: { ses_1: { type: "idle" } },
+      message: { ses_1: [unfinishedAssistantMessage("msg_1")] },
+      part: {
+        msg_1: [runningTool("tool_1", "msg_1"), completedTool("tool_2", "msg_1"), pendingTool("tool_3", "msg_1")],
+      },
+    })
+
+    const result = interruptedTurnToolParts(store, "ses_1", 5000)
+    expect(result).not.toBeNull()
+    const statuses = result!.parts.map((part) => (part as { state: { status: string } }).state.status)
+    expect(statuses).toEqual(["error", "completed", "error"])
+  })
+
+  test("no active parts → no change", () => {
+    const store = state({
+      session_status: { ses_1: { type: "idle" } },
+      message: { ses_1: [unfinishedAssistantMessage("msg_1")] },
+      part: { msg_1: [completedTool("tool_2", "msg_1")] },
+    })
+    expect(interruptedTurnToolParts(store, "ses_1")).toBeNull()
+  })
+})
diff --git a/packages/ui/src/sync/__tests__/materialization.test.ts b/packages/ui/src/sync/__tests__/materialization.test.ts
index cb7ce546..1f72ed70 100644
--- a/packages/ui/src/sync/__tests__/materialization.test.ts
+++ b/packages/ui/src/sync/__tests__/materialization.test.ts
@@ -167,6 +167,39 @@ describe("materializeSessionSnapshots", () => {
     expect(mergedPart.state?.time?.end).toBe(2000)
   })
 
+  test("does not regress a locally interrupted tool (error + end) when a stale running snapshot arrives", () => {
+    // The #2577 mark writes status "error" + end time; a later stale refresh
+    // that still reports the part as running must not undo it.
+    const interruptedTool = {
+      id: "prt_1",
+      messageID: "msg_1",
+      sessionID: "ses_1",
+      type: "tool",
+      state: { status: "error", error: "Interrupted", time: { start: 1000, end: 5000 } },
+    } as unknown as Part
+    const staleRunningTool = {
+      id: "prt_1",
+      messageID: "msg_1",
+      sessionID: "ses_1",
+      type: "tool",
+      state: { status: "running", time: { start: 1000 } },
+    } as unknown as Part
+    const state = {
+      message: { ses_1: [message("msg_1")] },
+      part: { msg_1: [interruptedTool] },
+    }
+
+    const result = materializeSessionSnapshots(
+      state,
+      "ses_1",
+      [{ info: message("msg_1"), parts: [staleRunningTool] }],
+    )
+
+    expect(result.part.msg_1[0]).toBe(interruptedTool)
+    expect(result.part.msg_1[0]).not.toBe(staleRunningTool)
+    expect((result.part.msg_1[0] as { state: { status: string } }).state.status).toBe("error")
+  })
+
   test("does not regress a completed tool when a stale running snapshot arrives", () => {
     const completedTool = {
       id: "prt_1",
diff --git a/packages/ui/src/sync/sync-context.tsx b/packages/ui/src/sync/sync-context.tsx
index b4ff6c19..846e6fcc 100644
--- a/packages/ui/src/sync/sync-context.tsx
+++ b/packages/ui/src/sync/sync-context.tsx
@@ -628,6 +628,19 @@ async function resyncDirectorySessionStatuses(
   applySessionStatusSnapshot(store, nextStatuses, candidateSessionIds, mode)
   if (mode === "authoritative") {
     applyGlobalSessionStatusSnapshot(directory, nextStatuses, candidateSessionIds)
+    // An authoritative snapshot that settles sessions previously observed
+    // busy/retry can orphan running tool parts (managed process died
+    // mid-turn, #2577): finalize them now. The snapshot write above already
+    // lowered their status to explicit idle, which is the gate the helper
+    // requires — a session the snapshot reports busy stays untouched.
+    for (const sessionId of candidateSessionIds) {
+      const interrupted = interruptedTurnToolParts(store.getState(), sessionId)
+      if (interrupted) {
+        store.setState((state) => ({
+          part: { ...state.part, [interrupted.messageID]: interrupted.parts },
+        }))
+      }
+    }
   }
   return nextStatuses
 }
@@ -1758,11 +1771,98 @@ function handleEvent(
         messageID,
       })
     }
+    // The reducer already wrote the idle/error status into `draft`; mark the
+    // orphaned tools using the batched state and publish through the batch.
+    if (sessionID) {
+      const interrupted = interruptedTurnToolParts(state, sessionID)
+      if (interrupted) {
+        cloneField("part", (value) => ({ ...(value ?? {}) }))
+        ;(draft as DirectoryStore).part[interrupted.messageID] = interrupted.parts
+        if (batch) {
+          batch.states.set(store, draft as DirectoryStore)
+          batch.changedStores.add(store)
+        } else {
+          store.setState({ part: { ...(store.getState().part), [interrupted.messageID]: interrupted.parts } })
+        }
+      }
+    }
   }
 
   updateRoutingIndexFromEvent(routingIndex, resolvedDirectory, payload)
 }
 
+// ---------------------------------------------------------------------------
+// Interrupted-turn reconciliation
+//
+// A managed OpenCode process can die mid-turn (crash, health-check restart).
+// The persisted turn then never settles: the trailing assistant message has
+// no `time.completed` and its tool parts stay `pending`/`running` forever —
+// the server never finalizes them (anomalyco/opencode#19023). The
+// settle-triggered tail refresh above refetches the same stale records, so
+// the UI would keep running tool timers and "working" styling indefinitely
+// (#2577).
+//
+// OpenCode keeps a turn's session busy while it is genuinely alive —
+// including while waiting for a question/permission reply — so once a
+// session is AUTHORITATIVELY settled (a `session.idle`/`session.error`
+// event, or an authoritative status snapshot that lowers a previously busy
+// session) and the trailing assistant message is still unfinished with
+// active tool parts and no pending question/permission, the turn is
+// definitively interrupted. Finalize the orphaned parts locally as
+// `error`/`Interrupted` with an end time — the same shape OpenCode itself
+// writes for cancelled tools. A later terminal part event or a refresh that
+// carries the true terminal state supersedes the mark; a stale refresh that
+// still reports `running` is rejected by the reducer's and the materializer's
+// final-status preservation.
+export function interruptedTurnToolParts(
+  state: DirectoryStore,
+  sessionID: string,
+  now = Date.now(),
+): { messageID: string; parts: Part[] } | null {
+  if ((state.question?.[sessionID] ?? []).length > 0) return null
+  if ((state.permission?.[sessionID] ?? []).length > 0) return null
+
+  const status = state.session_status?.[sessionID]
+  if (!status || status.type !== "idle") {
+    // Absent status is "unknown", not settled (the reducer maps both
+    // session.idle and session.error to {type:"idle"}): never judge an
+    // interrupted turn without an authoritative settle signal.
+    return null
+  }
+
+  const messageID = getStaleRunningToolMessageID(state, sessionID)
+  if (!messageID) return null
+  const message = (state.message[sessionID] ?? []).find((candidate) => candidate.id === messageID)
+  if (!message) return null
+  if (typeof (message as { time?: { completed?: unknown } }).time?.completed === "number") {
+    // The turn finished; a missed terminal tool event is the tail refresh's
+    // job, not an interruption.
+    return null
+  }
+
+  const current = state.part[messageID]
+  if (!current) return null
+
+  let changed = false
+  const nextParts = current.map((part) => {
+    if (part.type !== "tool") return part
+    const partState = (part as { state?: { status?: unknown; time?: { start?: number } } }).state
+    if (!partState) return part
+    if (partState.status !== "pending" && partState.status !== "running") return part
+    changed = true
+    return {
+      ...part,
+      state: {
+        ...partState,
+        status: "error",
+        error: "Interrupted",
+        time: { ...(partState.time ?? {}), end: now },
+      },
+    } as Part
+  })
+  return changed ? { messageID, parts: nextParts } : null
+}
+
 // ---------------------------------------------------------------------------
 // Provider
 // ---------------------------------------------------------------------------

From 856ab452dcabd271d34b568a13689a42cac4bf58 Mon Sep 17 00:00:00 2001
From: Serhii Dziupin <serkraser@gmail.com>
Date: Wed, 5 Aug 2026 14:16:18 +0300
Subject: [PATCH 28/57] docs(server): document onOpenCodeRestarted lifecycle
 dependency

---
 packages/web/server/lib/opencode/DOCUMENTATION.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/web/server/lib/opencode/DOCUMENTATION.md b/packages/web/server/lib/opencode/DOCUMENTATION.md
index dfd520c0..3996860f 100644
--- a/packages/web/server/lib/opencode/DOCUMENTATION.md
+++ b/packages/web/server/lib/opencode/DOCUMENTATION.md
@@ -112,7 +112,7 @@ This module provides OpenCode server integration utilities for the web server ru
 The runtime maintains active-session count incrementally from idempotent activity phase transitions. Upstream stall-timeout and lifecycle health checks read it in O(1); the hourly cleanup removes activity phases older than 24 hours without broadcasting synthetic state transitions. Snapshot generation remains reserved for the session-activity API.
 
 ## Public exports (lifecycle.js)
-- `createOpenCodeLifecycleRuntime(dependencies)`: creates lifecycle runtime for managed/external OpenCode process orchestration.
+- `createOpenCodeLifecycleRuntime(dependencies)`: creates lifecycle runtime for managed/external OpenCode process orchestration. The optional `onOpenCodeRestarted` dependency (default `null`) is fired after a successful managed restart; `index.js` wires it to `messageStreamRuntime.rebindUpstream()` so event-stream readers rebind to the possibly-new port (a restart can land on a new port while an orphaned process keeps the old one, which would otherwise leave the chat UI silent — issue #2638).
 - Returned API:
   - `startOpenCode()`
   - `restartOpenCode()`

From 341b4b45c8900fcb627b42e5e7979eb4b426ae7b Mon Sep 17 00:00:00 2001
From: Serhii Dziupin <serkraser@gmail.com>
Date: Wed, 5 Aug 2026 13:26:46 +0000
Subject: [PATCH 29/57] fix(ui): stop painting git activity dots on non-git
 rail surfaces

The badge PR inverted showActivityDot to !== 'git', so editor/terminal/diff
picked up the blue activity dot whenever git had changes. Git already shows
a numeric badge; other surfaces should stay quiet. Also split the count
aria/tooltip strings into singular/plural keys.

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>
---
 .../components/layout/ContextPanelRail.tsx    | 20 ++++++++++++++-----
 packages/ui/src/lib/i18n/messages/de.ts       |  6 ++++--
 packages/ui/src/lib/i18n/messages/en.ts       |  6 ++++--
 packages/ui/src/lib/i18n/messages/es.ts       |  6 ++++--
 packages/ui/src/lib/i18n/messages/fr.ts       |  6 ++++--
 packages/ui/src/lib/i18n/messages/ja.ts       |  6 ++++--
 packages/ui/src/lib/i18n/messages/ko.ts       |  6 ++++--
 packages/ui/src/lib/i18n/messages/pl.ts       |  6 ++++--
 packages/ui/src/lib/i18n/messages/pt-BR.ts    |  6 ++++--
 packages/ui/src/lib/i18n/messages/uk.ts       |  6 ++++--
 packages/ui/src/lib/i18n/messages/zh-CN.ts    |  6 ++++--
 packages/ui/src/lib/i18n/messages/zh-TW.ts    |  6 ++++--
 12 files changed, 59 insertions(+), 27 deletions(-)

diff --git a/packages/ui/src/components/layout/ContextPanelRail.tsx b/packages/ui/src/components/layout/ContextPanelRail.tsx
index 54b5d78c..f7f5ce0d 100644
--- a/packages/ui/src/components/layout/ContextPanelRail.tsx
+++ b/packages/ui/src/components/layout/ContextPanelRail.tsx
@@ -284,8 +284,8 @@ export const ContextPanelRail: React.FC = () => {
         <SortableContext items={surfaces.map((surface) => surface.id)} strategy={verticalListSortingStrategy}>
           {surfaces.map((surface, index) => {
             const label = t(surface.labelKey);
-            // The Git surface carries its changed-files count as a numeric
-            // badge; other surfaces keep the plain activity dot.
+            // Git shows a numeric badge instead of the old activity dot.
+            // Other surfaces never inherit git's changed-files signal.
             const gitChangedCount = surface.id === 'git' ? changedFilesCount : 0;
             const badgeCount = gitChangedCount > 0 ? gitChangedCount : null;
             return (
@@ -293,15 +293,25 @@ export const ContextPanelRail: React.FC = () => {
                 key={surface.id}
                 surface={surface}
                 isActive={activeMode === surface.mode}
-                showActivityDot={surface.id !== 'git' && changedFilesCount > 0}
+                showActivityDot={false}
                 label={label}
                 description={t(surface.descriptionKey)}
                 badgeCount={badgeCount}
                 badgeAriaLabel={badgeCount !== null
-                  ? t('contextRail.surface.git.changesCountAria', { label, count: badgeCount })
+                  ? t(
+                      badgeCount === 1
+                        ? 'contextRail.surface.git.changesCountAriaSingle'
+                        : 'contextRail.surface.git.changesCountAriaPlural',
+                      { label, count: badgeCount },
+                    )
                   : null}
                 badgeDescription={badgeCount !== null
-                  ? t('contextRail.surface.git.changesCountTooltip', { count: badgeCount })
+                  ? t(
+                      badgeCount === 1
+                        ? 'contextRail.surface.git.changesCountTooltipSingle'
+                        : 'contextRail.surface.git.changesCountTooltipPlural',
+                      { count: badgeCount },
+                    )
                   : null}
                 orderNumber={index + 1}
                 showOrderNumber={revealNumbers}
diff --git a/packages/ui/src/lib/i18n/messages/de.ts b/packages/ui/src/lib/i18n/messages/de.ts
index ffa3702f..0814ed97 100644
--- a/packages/ui/src/lib/i18n/messages/de.ts
+++ b/packages/ui/src/lib/i18n/messages/de.ts
@@ -2828,8 +2828,10 @@ export const dict = {
   'contextPanel.editorEmpty.description': 'Wählen Sie etwas aus der Seitenleiste aus, um Kontext anzuzeigen.',
   'contextRail.surface.editor.description': 'Bearbeitungskontext',
   'contextRail.surface.git.description': 'Git-Kontext',
-  'contextRail.surface.git.changesCountAria': '{label}, {count} geänderte Dateien',
-  'contextRail.surface.git.changesCountTooltip': '{count} geänderte Dateien',
+  'contextRail.surface.git.changesCountAriaSingle': '{label}, {count} geänderte Datei',
+  'contextRail.surface.git.changesCountAriaPlural': '{label}, {count} geänderte Dateien',
+  'contextRail.surface.git.changesCountTooltipSingle': '{count} geänderte Datei',
+  'contextRail.surface.git.changesCountTooltipPlural': '{count} geänderte Dateien',
   'contextRail.surface.terminal.description': 'Terminal-Kontext',
   'contextRail.surface.diff.description': 'Diff-Kontext',
   'contextPanel.mode.walkthrough': 'Walkthrough',
diff --git a/packages/ui/src/lib/i18n/messages/en.ts b/packages/ui/src/lib/i18n/messages/en.ts
index 641e4944..895faaae 100644
--- a/packages/ui/src/lib/i18n/messages/en.ts
+++ b/packages/ui/src/lib/i18n/messages/en.ts
@@ -1106,8 +1106,10 @@ export const dict = {
   'contextPanel.editorEmpty.description': 'Pick a file from the tree to start editing.',
   'contextRail.surface.editor.description': 'Edit project files',
   'contextRail.surface.git.description': 'Commits, branches, and pull requests',
-  'contextRail.surface.git.changesCountAria': '{label}, {count} changed files',
-  'contextRail.surface.git.changesCountTooltip': '{count} changed files',
+  'contextRail.surface.git.changesCountAriaSingle': '{label}, {count} changed file',
+  'contextRail.surface.git.changesCountAriaPlural': '{label}, {count} changed files',
+  'contextRail.surface.git.changesCountTooltipSingle': '{count} changed file',
+  'contextRail.surface.git.changesCountTooltipPlural': '{count} changed files',
   'contextRail.surface.terminal.description': 'Built-in terminal',
   'contextRail.surface.diff.description': 'Review working changes',
   'contextPanel.mode.walkthrough': 'Walkthrough',
diff --git a/packages/ui/src/lib/i18n/messages/es.ts b/packages/ui/src/lib/i18n/messages/es.ts
index a125d533..21bcd484 100644
--- a/packages/ui/src/lib/i18n/messages/es.ts
+++ b/packages/ui/src/lib/i18n/messages/es.ts
@@ -1107,8 +1107,10 @@ export const dict: Record<I18nKey, string> = {
   "contextPanel.editorEmpty.description": "Elige un archivo del árbol para empezar a editar.",
   "contextRail.surface.editor.description": "Editar archivos del proyecto",
   "contextRail.surface.git.description": "Commits, ramas y pull requests",
-  "contextRail.surface.git.changesCountAria": "{label}, {count} archivos modificados",
-  "contextRail.surface.git.changesCountTooltip": "{count} archivos modificados",
+  "contextRail.surface.git.changesCountAriaSingle": "{label}, {count} archivo modificado",
+  "contextRail.surface.git.changesCountAriaPlural": "{label}, {count} archivos modificados",
+  "contextRail.surface.git.changesCountTooltipSingle": "{count} archivo modificado",
+  "contextRail.surface.git.changesCountTooltipPlural": "{count} archivos modificados",
   "contextRail.surface.terminal.description": "Terminal integrada",
   "contextRail.surface.diff.description": "Revisar cambios en curso",
   "contextPanel.mode.walkthrough": "Recorrido",
diff --git a/packages/ui/src/lib/i18n/messages/fr.ts b/packages/ui/src/lib/i18n/messages/fr.ts
index 1fa0637e..a94c8ff7 100644
--- a/packages/ui/src/lib/i18n/messages/fr.ts
+++ b/packages/ui/src/lib/i18n/messages/fr.ts
@@ -931,8 +931,10 @@ export const dict = {
   'contextPanel.editorEmpty.description': 'Choisissez un fichier dans l’arborescence pour commencer.',
   'contextRail.surface.editor.description': 'Modifier les fichiers du projet',
   'contextRail.surface.git.description': 'Commits, branches et pull requests',
-  'contextRail.surface.git.changesCountAria': '{label}, {count} fichiers modifiés',
-  'contextRail.surface.git.changesCountTooltip': '{count} fichiers modifiés',
+  'contextRail.surface.git.changesCountAriaSingle': '{label}, {count} fichier modifié',
+  'contextRail.surface.git.changesCountAriaPlural': '{label}, {count} fichiers modifiés',
+  'contextRail.surface.git.changesCountTooltipSingle': '{count} fichier modifié',
+  'contextRail.surface.git.changesCountTooltipPlural': '{count} fichiers modifiés',
   'contextRail.surface.terminal.description': 'Terminal intégré',
   'contextRail.surface.diff.description': 'Passer en revue les modifications',
   'contextPanel.mode.walkthrough': 'Parcours',
diff --git a/packages/ui/src/lib/i18n/messages/ja.ts b/packages/ui/src/lib/i18n/messages/ja.ts
index 83d7fb32..a135d9e5 100644
--- a/packages/ui/src/lib/i18n/messages/ja.ts
+++ b/packages/ui/src/lib/i18n/messages/ja.ts
@@ -1103,8 +1103,10 @@ export const dict: Record<I18nKey, string> = {
   'contextPanel.editorEmpty.description': 'ツリーからファイルを選んで編集を始めましょう。',
   'contextRail.surface.editor.description': 'プロジェクトのファイルを編集',
   'contextRail.surface.git.description': 'コミット・ブランチ・プルリクエスト',
-  'contextRail.surface.git.changesCountAria': '{label}、変更ファイル{count}件',
-  'contextRail.surface.git.changesCountTooltip': '変更ファイル{count}件',
+  'contextRail.surface.git.changesCountAriaSingle': '{label}、変更ファイル{count}件',
+  'contextRail.surface.git.changesCountAriaPlural': '{label}、変更ファイル{count}件',
+  'contextRail.surface.git.changesCountTooltipSingle': '変更ファイル{count}件',
+  'contextRail.surface.git.changesCountTooltipPlural': '変更ファイル{count}件',
   'contextRail.surface.terminal.description': '内蔵ターミナル',
   'contextRail.surface.diff.description': '作業中の変更をレビュー',
   'contextPanel.mode.walkthrough': 'ウォークスルー',
diff --git a/packages/ui/src/lib/i18n/messages/ko.ts b/packages/ui/src/lib/i18n/messages/ko.ts
index 986ff3bd..84c41bcc 100644
--- a/packages/ui/src/lib/i18n/messages/ko.ts
+++ b/packages/ui/src/lib/i18n/messages/ko.ts
@@ -1107,8 +1107,10 @@ export const dict: Record<I18nKey, string> = {
   'contextPanel.editorEmpty.description': '트리에서 파일을 선택해 편집을 시작하세요.',
   'contextRail.surface.editor.description': '프로젝트 파일 편집',
   'contextRail.surface.git.description': '커밋, 브랜치, 풀 리퀘스트',
-  'contextRail.surface.git.changesCountAria': '{label}, 변경된 파일 {count}개',
-  'contextRail.surface.git.changesCountTooltip': '변경된 파일 {count}개',
+  'contextRail.surface.git.changesCountAriaSingle': '{label}, 변경된 파일 {count}개',
+  'contextRail.surface.git.changesCountAriaPlural': '{label}, 변경된 파일 {count}개',
+  'contextRail.surface.git.changesCountTooltipSingle': '변경된 파일 {count}개',
+  'contextRail.surface.git.changesCountTooltipPlural': '변경된 파일 {count}개',
   'contextRail.surface.terminal.description': '내장 터미널',
   'contextRail.surface.diff.description': '작업 중인 변경 사항 검토',
   'contextPanel.mode.walkthrough': '워크스루',
diff --git a/packages/ui/src/lib/i18n/messages/pl.ts b/packages/ui/src/lib/i18n/messages/pl.ts
index ad308b23..3e1cb4e4 100644
--- a/packages/ui/src/lib/i18n/messages/pl.ts
+++ b/packages/ui/src/lib/i18n/messages/pl.ts
@@ -1419,8 +1419,10 @@ export const dict: Record<I18nKey, string> = {
   'contextPanel.editorEmpty.description': 'Wybierz plik z drzewa, aby rozpocząć edycję.',
   'contextRail.surface.editor.description': 'Edytuj pliki projektu',
   'contextRail.surface.git.description': 'Commity, gałęzie i pull requesty',
-  'contextRail.surface.git.changesCountAria': '{label}, {count} zmienionych plików',
-  'contextRail.surface.git.changesCountTooltip': '{count} zmienionych plików',
+  'contextRail.surface.git.changesCountAriaSingle': '{label}, {count} zmieniony plik',
+  'contextRail.surface.git.changesCountAriaPlural': '{label}, {count} zmienionych plików',
+  'contextRail.surface.git.changesCountTooltipSingle': '{count} zmieniony plik',
+  'contextRail.surface.git.changesCountTooltipPlural': '{count} zmienionych plików',
   'contextRail.surface.terminal.description': 'Wbudowany terminal',
   'contextRail.surface.diff.description': 'Przeglądaj bieżące zmiany',
   'contextPanel.mode.walkthrough': 'Przewodnik',
diff --git a/packages/ui/src/lib/i18n/messages/pt-BR.ts b/packages/ui/src/lib/i18n/messages/pt-BR.ts
index d2e16295..333666ce 100644
--- a/packages/ui/src/lib/i18n/messages/pt-BR.ts
+++ b/packages/ui/src/lib/i18n/messages/pt-BR.ts
@@ -1107,8 +1107,10 @@ export const dict: Record<I18nKey, string> = {
   "contextPanel.editorEmpty.description": "Escolha um arquivo na árvore para começar a editar.",
   "contextRail.surface.editor.description": "Editar arquivos do projeto",
   "contextRail.surface.git.description": "Commits, branches e pull requests",
-  "contextRail.surface.git.changesCountAria": "{label}, {count} arquivos modificados",
-  "contextRail.surface.git.changesCountTooltip": "{count} arquivos modificados",
+  "contextRail.surface.git.changesCountAriaSingle": "{label}, {count} arquivo modificado",
+  "contextRail.surface.git.changesCountAriaPlural": "{label}, {count} arquivos modificados",
+  "contextRail.surface.git.changesCountTooltipSingle": "{count} arquivo modificado",
+  "contextRail.surface.git.changesCountTooltipPlural": "{count} arquivos modificados",
   "contextRail.surface.terminal.description": "Terminal integrado",
   "contextRail.surface.diff.description": "Revisar alterações em andamento",
   "contextPanel.mode.walkthrough": "Percurso",
diff --git a/packages/ui/src/lib/i18n/messages/uk.ts b/packages/ui/src/lib/i18n/messages/uk.ts
index 4e61c8f5..2680f0c3 100644
--- a/packages/ui/src/lib/i18n/messages/uk.ts
+++ b/packages/ui/src/lib/i18n/messages/uk.ts
@@ -1107,8 +1107,10 @@ export const dict: Record<I18nKey, string> = {
   "contextPanel.editorEmpty.description": "Виберіть файл у дереві, щоб почати редагування.",
   "contextRail.surface.editor.description": "Редагування файлів проєкту",
   "contextRail.surface.git.description": "Коміти, гілки та pull request-и",
-  "contextRail.surface.git.changesCountAria": "{label}, {count} змінених файлів",
-  "contextRail.surface.git.changesCountTooltip": "{count} змінених файлів",
+  "contextRail.surface.git.changesCountAriaSingle": "{label}, {count} змінений файл",
+  "contextRail.surface.git.changesCountAriaPlural": "{label}, {count} змінених файлів",
+  "contextRail.surface.git.changesCountTooltipSingle": "{count} змінений файл",
+  "contextRail.surface.git.changesCountTooltipPlural": "{count} змінених файлів",
   "contextRail.surface.terminal.description": "Вбудований термінал",
   "contextRail.surface.diff.description": "Перегляд поточних змін",
   "contextPanel.mode.walkthrough": "Розбір",
diff --git a/packages/ui/src/lib/i18n/messages/zh-CN.ts b/packages/ui/src/lib/i18n/messages/zh-CN.ts
index 4d262c92..5a36af20 100644
--- a/packages/ui/src/lib/i18n/messages/zh-CN.ts
+++ b/packages/ui/src/lib/i18n/messages/zh-CN.ts
@@ -1107,8 +1107,10 @@ export const dict: Record<I18nKey, string> = {
   'contextPanel.editorEmpty.description': '从文件树中选择一个文件开始编辑。',
   'contextRail.surface.editor.description': '编辑项目文件',
   'contextRail.surface.git.description': '提交、分支和拉取请求',
-  'contextRail.surface.git.changesCountAria': '{label}，{count} 个更改的文件',
-  'contextRail.surface.git.changesCountTooltip': '{count} 个更改的文件',
+  'contextRail.surface.git.changesCountAriaSingle': '{label}，{count} 个更改的文件',
+  'contextRail.surface.git.changesCountAriaPlural': '{label}，{count} 个更改的文件',
+  'contextRail.surface.git.changesCountTooltipSingle': '{count} 个更改的文件',
+  'contextRail.surface.git.changesCountTooltipPlural': '{count} 个更改的文件',
   'contextRail.surface.terminal.description': '内置终端',
   'contextRail.surface.diff.description': '查看工作区更改',
   'contextPanel.mode.walkthrough': '导读',
diff --git a/packages/ui/src/lib/i18n/messages/zh-TW.ts b/packages/ui/src/lib/i18n/messages/zh-TW.ts
index e323ed7f..846aa35c 100644
--- a/packages/ui/src/lib/i18n/messages/zh-TW.ts
+++ b/packages/ui/src/lib/i18n/messages/zh-TW.ts
@@ -1119,8 +1119,10 @@ export const dict: Record<I18nKey, string> = {
   'contextPanel.editorEmpty.description': '從檔案樹選擇檔案開始編輯。',
   'contextRail.surface.editor.description': '編輯專案檔案',
   'contextRail.surface.git.description': '提交、分支與拉取請求',
-  'contextRail.surface.git.changesCountAria': '{label}，{count} 個變更的檔案',
-  'contextRail.surface.git.changesCountTooltip': '{count} 個變更的檔案',
+  'contextRail.surface.git.changesCountAriaSingle': '{label}，{count} 個變更的檔案',
+  'contextRail.surface.git.changesCountAriaPlural': '{label}，{count} 個變更的檔案',
+  'contextRail.surface.git.changesCountTooltipSingle': '{count} 個變更的檔案',
+  'contextRail.surface.git.changesCountTooltipPlural': '{count} 個變更的檔案',
   'contextRail.surface.terminal.description': '內建終端機',
   'contextRail.surface.diff.description': '檢視工作區變更',
   'contextPanel.mode.walkthrough': '導讀',

From 938e58868fcebedcf324e345e10deef8b7106937 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Wed, 5 Aug 2026 17:11:41 +0000
Subject: [PATCH 30/57] fix(ui): let Escape reach the terminal PTY from the
 context panel

The desktop ContextPanel captured Escape on the panel aside and closed
the whole pane before ghostty-web's bubble-phase listener could forward
the key. Skip closing when the event target is inside the terminal so
apps like Vim can leave insert mode.

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>
---
 .../ui/src/components/layout/ContextPanel.tsx |   8 +
 .../contextPanelEscapeClosesTerminal.test.ts  | 187 ++++++++++++++++++
 2 files changed, 195 insertions(+)
 create mode 100644 packages/ui/src/components/layout/__tests__/contextPanelEscapeClosesTerminal.test.ts

diff --git a/packages/ui/src/components/layout/ContextPanel.tsx b/packages/ui/src/components/layout/ContextPanel.tsx
index f48dc445..d0b1f9c1 100644
--- a/packages/ui/src/components/layout/ContextPanel.tsx
+++ b/packages/ui/src/components/layout/ContextPanel.tsx
@@ -45,6 +45,7 @@ import {
   type EmbeddedSessionRuntimeBootstrap,
 } from './contextPanelEmbeddedChat';
 import { getContextSurfaceWidthFraction } from '@/lib/surfaces/registry';
+import { isTerminalEventTarget } from '@/lib/terminalFocus';
 import {
   type PreviewElementMetadata,
   isPreviewElementMetadata,
@@ -2453,6 +2454,13 @@ export const ContextPanel: React.FC = () => {
       return;
     }
 
+    // Terminal owns Escape so the PTY receives it (e.g. Vim Normal mode).
+    // ghostty-web listens in the bubble phase; stopping capture here would
+    // swallow the key before the terminal ever sees it (issue #2644).
+    if (isTerminalEventTarget(event.target)) {
+      return;
+    }
+
     event.preventDefault();
     event.stopPropagation();
     handleClose();
diff --git a/packages/ui/src/components/layout/__tests__/contextPanelEscapeClosesTerminal.test.ts b/packages/ui/src/components/layout/__tests__/contextPanelEscapeClosesTerminal.test.ts
new file mode 100644
index 00000000..63bca320
--- /dev/null
+++ b/packages/ui/src/components/layout/__tests__/contextPanelEscapeClosesTerminal.test.ts
@@ -0,0 +1,187 @@
+/**
+ * Regression guard for https://github.com/openchamber/openchamber/issues/2644
+ *
+ * Escape while focus is inside the terminal must reach the PTY (e.g. Vim
+ * Normal mode). The context panel still closes on Escape when focus is on
+ * non-terminal panel chrome.
+ */
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const contextPanelSource = readFileSync(join(__dirname, '..', 'ContextPanel.tsx'), 'utf-8');
+const mobileWorkspaceDrawerSource = readFileSync(
+  join(__dirname, '..', '..', '..', 'apps', 'MobileWorkspaceDrawer.tsx'),
+  'utf-8',
+);
+
+describe('issue #2644: Escape in terminal must not close the context panel', () => {
+  test('the context panel captures Escape at the panel level', () => {
+    expect(contextPanelSource).toContain('onKeyDownCapture={handlePanelKeyDownCapture}');
+  });
+
+  test('the capture handler skips closing when the event target is inside the terminal', () => {
+    const start = contextPanelSource.indexOf('const handlePanelKeyDownCapture = React.useCallback(');
+    expect(start).toBeGreaterThan(-1);
+    const end = contextPanelSource.indexOf('}, [handleClose]);', start);
+    expect(end).toBeGreaterThan(start);
+    const handler = contextPanelSource.slice(start, end);
+
+    expect(handler).toContain("event.key !== 'Escape'");
+    expect(handler).toContain('isTerminalEventTarget(event.target)');
+    expect(handler).toContain('event.preventDefault()');
+    expect(handler).toContain('event.stopPropagation()');
+    expect(handler).toContain('handleClose()');
+
+    // Guard must return before preventDefault/stopPropagation so ghostty-web's
+    // bubble-phase keydown listener can forward Escape to the PTY.
+    const guardIndex = handler.indexOf('isTerminalEventTarget(event.target)');
+    const preventIndex = handler.indexOf('event.preventDefault()');
+    expect(guardIndex).toBeGreaterThan(-1);
+    expect(preventIndex).toBeGreaterThan(guardIndex);
+  });
+
+  test('ContextPanel imports the shared terminal focus helper', () => {
+    expect(contextPanelSource).toContain("from '@/lib/terminalFocus'");
+    expect(contextPanelSource).toContain('isTerminalEventTarget');
+  });
+
+  test('mobile drawer keeps its terminal Escape exception', () => {
+    const handlerStart = mobileWorkspaceDrawerSource.indexOf("if (event.key === 'Escape'");
+    expect(handlerStart).toBeGreaterThan(-1);
+    const handler = mobileWorkspaceDrawerSource.slice(handlerStart, handlerStart + 200);
+    expect(handler).toContain("tabRef.current !== 'terminal'");
+  });
+});
+
+type Listener = { capture: boolean; onEvent: (event: SimulatedEvent) => void };
+type SimulatedEvent = {
+  type: string;
+  defaultPrevented: boolean;
+  propagationStopped: boolean;
+  target: SimNode;
+  preventDefault(): void;
+  stopPropagation(): void;
+};
+
+class SimNode {
+  readonly children: SimNode[] = [];
+  private listeners: Listener[] = [];
+  private parent: SimNode | null = null;
+
+  addListener(listener: Listener): void {
+    this.listeners.push(listener);
+  }
+
+  attach(child: SimNode): void {
+    child.parent = this;
+    this.children.push(child);
+  }
+
+  dispatch(type: string): SimulatedEvent {
+    const buildPath = (target: SimNode): SimNode[] => {
+      const ancestors: SimNode[] = [];
+      let cursor: SimNode | null = target;
+      while (cursor !== null) {
+        ancestors.push(cursor);
+        cursor = cursor.parent;
+      }
+      ancestors.reverse();
+      return ancestors;
+    };
+    const path = buildPath(this);
+
+    const event: SimulatedEvent = {
+      type,
+      defaultPrevented: false,
+      propagationStopped: false,
+      target: this,
+      preventDefault() {
+        event.defaultPrevented = true;
+      },
+      stopPropagation() {
+        event.propagationStopped = true;
+      },
+    };
+
+    for (let i = 0; i < path.length; i += 1) {
+      if (event.propagationStopped) return event;
+      for (const listener of path[i].listeners) {
+        if (!listener.capture) continue;
+        listener.onEvent(event);
+        if (event.propagationStopped) return event;
+      }
+    }
+    for (let i = path.length - 1; i >= 0; i -= 1) {
+      if (event.propagationStopped) return event;
+      for (const listener of path[i].listeners) {
+        if (listener.capture) continue;
+        listener.onEvent(event);
+        if (event.propagationStopped) return event;
+      }
+    }
+    return event;
+  }
+}
+
+describe('issue #2644: fixed Escape propagation to the terminal', () => {
+  test('when the panel skips terminal Escape, the terminal bubble handler receives it', () => {
+    const panel = new SimNode();
+    const terminalContainer = new SimNode();
+    panel.attach(terminalContainer);
+
+    const calls: string[] = [];
+    const panelEscapeHandler = (event: SimulatedEvent) => {
+      // Fixed behavior: do not close / stop when the target is the terminal.
+      if (event.target === terminalContainer) {
+        calls.push('panel-capture-skipped');
+        return;
+      }
+      calls.push('panel-capture-closed');
+      event.preventDefault();
+      event.stopPropagation();
+    };
+    const terminalKeydownHandler = () => {
+      calls.push('terminal-bubble');
+    };
+
+    panel.addListener({ capture: true, onEvent: panelEscapeHandler });
+    terminalContainer.addListener({ capture: false, onEvent: terminalKeydownHandler });
+
+    const event = terminalContainer.dispatch('keydown');
+
+    expect(calls).toEqual(['panel-capture-skipped', 'terminal-bubble']);
+    expect(event.propagationStopped).toBe(false);
+    expect(event.defaultPrevented).toBe(false);
+  });
+
+  test('Escape outside the terminal still closes via the capture handler', () => {
+    const panel = new SimNode();
+    const headerButton = new SimNode();
+    const terminalContainer = new SimNode();
+    panel.attach(headerButton);
+    panel.attach(terminalContainer);
+
+    const calls: string[] = [];
+    panel.addListener({
+      capture: true,
+      onEvent: (event) => {
+        if (event.target === terminalContainer) return;
+        calls.push('panel-capture-closed');
+        event.preventDefault();
+        event.stopPropagation();
+      },
+    });
+    terminalContainer.addListener({
+      capture: false,
+      onEvent: () => calls.push('terminal-bubble'),
+    });
+
+    const event = headerButton.dispatch('keydown');
+    expect(calls).toEqual(['panel-capture-closed']);
+    expect(event.propagationStopped).toBe(true);
+    expect(event.defaultPrevented).toBe(true);
+  });
+});

From ee57088dfe7f9c342dd375f64f7999e07e1137bb Mon Sep 17 00:00:00 2001
From: Serhii Dziupin <serkraser@gmail.com>
Date: Wed, 5 Aug 2026 17:40:01 +0000
Subject: [PATCH 31/57] fix(fs): keep list paths in requested space through
 symlinks

Closes openchamber/openchamber#2627

Listing a directory through a workspace symlink was returning realpath
entry paths. The file tree then rejected nested expand toggles because
those paths fall outside the workspace root.

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>
---
 .../src/stores/useFilesViewTabsStore.test.ts  | 14 ++++
 packages/web/server/lib/fs/DOCUMENTATION.md   |  1 +
 packages/web/server/lib/fs/routes.js          | 28 ++++---
 packages/web/server/lib/fs/routes.test.js     | 75 +++++++++++++++++++
 4 files changed, 109 insertions(+), 9 deletions(-)

diff --git a/packages/ui/src/stores/useFilesViewTabsStore.test.ts b/packages/ui/src/stores/useFilesViewTabsStore.test.ts
index 1937e3e1..661959fc 100644
--- a/packages/ui/src/stores/useFilesViewTabsStore.test.ts
+++ b/packages/ui/src/stores/useFilesViewTabsStore.test.ts
@@ -29,6 +29,20 @@ describe('useFilesViewTabsStore', () => {
     expect(useFilesViewTabsStore.getState().byRoot[root]?.expandedPaths).toEqual(['/repo/src']);
   });
 
+  test('rejects realpath children of workspace symlinks (issue 2627)', () => {
+    const root = '/workspace';
+    const store = useFilesViewTabsStore.getState();
+
+    store.toggleExpandedPath(root, '/workspace/pkg');
+    store.toggleExpandedPath(root, '/real/pkg/src');
+    store.toggleExpandedPath(root, '/workspace/pkg/src');
+
+    expect(useFilesViewTabsStore.getState().byRoot[root]?.expandedPaths).toEqual([
+      '/workspace/pkg',
+      '/workspace/pkg/src',
+    ]);
+  });
+
   test('removes stale expanded paths by prefix without closing files', () => {
     const root = '/repo';
     const store = useFilesViewTabsStore.getState();
diff --git a/packages/web/server/lib/fs/DOCUMENTATION.md b/packages/web/server/lib/fs/DOCUMENTATION.md
index bc853ce9..6c82a832 100644
--- a/packages/web/server/lib/fs/DOCUMENTATION.md
+++ b/packages/web/server/lib/fs/DOCUMENTATION.md
@@ -35,3 +35,4 @@ Own filesystem API behavior for the web server runtime, including workspace-boun
 ## Notes for contributors
 - Keep filesystem policy (workspace root checks, error mapping, exec timeout behavior) inside this module, not in the composition root.
 - If adding new `/api/fs/*` endpoints, add them in `routes.js` and extend this document.
+- `GET /api/fs/list` may resolve symlinks with `realpath` to read directory contents, but the response `path` and each entry `path` must stay in the caller's requested path space (`path.join(requestedPath, name)`). Returning real paths breaks file-tree expansion for directories reached through workspace symlinks.
diff --git a/packages/web/server/lib/fs/routes.js b/packages/web/server/lib/fs/routes.js
index 81a29d8e..95887cf5 100644
--- a/packages/web/server/lib/fs/routes.js
+++ b/packages/web/server/lib/fs/routes.js
@@ -454,7 +454,7 @@ export const registerFsRoutes = (app, dependencies) => {
   // Non-cacheable commands always execute and are never stored.
   const runCommandWithGitReadCache = async ({ shell, shellFlag, command, resolvedCwd }) => {
     const cacheable = gitReadCacheTtlMs > 0 && isCacheableGitReadCommand(command);
-    const cacheKey = cacheable ? `${resolvedCwd}${normalizeCommand(command)}` : null;
+    const cacheKey = cacheable ? `${resolvedCwd}${normalizeCommand(command)}` : null;
 
     if (cacheKey) {
       const cached = gitReadCache.get(cacheKey);
@@ -1296,6 +1296,11 @@ export const registerFsRoutes = (app, dependencies) => {
       ? req.query.path.trim()
       : os.homedir();
     const respectGitignore = req.query.respectGitignore === 'true';
+    // Logical (requested) path stays in the caller's path space. Realpath is
+    // only used to read directory contents — returning real paths for entries
+    // breaks file-tree expansion when listing through a symlink, because the
+    // UI rejects expanded paths that fall outside the workspace root.
+    let requestedPath = '';
     let resolvedPath = '';
 
     const isPlansDirectory = (value) => {
@@ -1305,7 +1310,8 @@ export const registerFsRoutes = (app, dependencies) => {
     };
 
     try {
-      resolvedPath = await realpathCache.resolve(path.resolve(normalizeDirectoryPath(rawPath)));
+      requestedPath = path.resolve(normalizeDirectoryPath(rawPath));
+      resolvedPath = await realpathCache.resolve(requestedPath);
 
       const stats = await fsPromises.stat(resolvedPath);
       if (!stats.isDirectory()) {
@@ -1364,8 +1370,8 @@ export const registerFsRoutes = (app, dependencies) => {
 
       const entries = await Promise.all(
         dirents.map(async (dirent) => {
-          const entryPath = path.join(resolvedPath, dirent.name);
-          if (respectGitignore && ignoredPaths.has(entryPath)) {
+          const physicalEntryPath = path.join(resolvedPath, dirent.name);
+          if (respectGitignore && ignoredPaths.has(physicalEntryPath)) {
             return null;
           }
 
@@ -1374,7 +1380,7 @@ export const registerFsRoutes = (app, dependencies) => {
 
           if (!isDirectory && isSymbolicLink) {
             try {
-              const linkStats = await fsPromises.stat(entryPath);
+              const linkStats = await fsPromises.stat(physicalEntryPath);
               isDirectory = linkStats.isDirectory();
             } catch {
               isDirectory = false;
@@ -1383,7 +1389,7 @@ export const registerFsRoutes = (app, dependencies) => {
 
           return {
             name: dirent.name,
-            path: entryPath,
+            path: path.join(requestedPath, dirent.name),
             isDirectory,
             isFile: dirent.isFile(),
             isSymbolicLink,
@@ -1392,19 +1398,23 @@ export const registerFsRoutes = (app, dependencies) => {
       );
 
       return res.json({
-        path: resolvedPath,
+        path: requestedPath,
         entries: entries.filter(Boolean),
       });
     } catch (error) {
       const err = error;
       const code = err && typeof err === 'object' && 'code' in err ? err.code : undefined;
-      const isPlansPath = code === 'ENOENT' && (isPlansDirectory(resolvedPath) || isPlansDirectory(rawPath));
+      const isPlansPath = code === 'ENOENT' && (
+        isPlansDirectory(resolvedPath)
+        || isPlansDirectory(requestedPath)
+        || isPlansDirectory(rawPath)
+      );
       if (code !== 'ENOENT') {
         console.error('Failed to list directory:', error);
       }
       if (code === 'ENOENT') {
         if (isPlansPath) {
-          return res.json({ path: resolvedPath || rawPath, entries: [] });
+          return res.json({ path: requestedPath || resolvedPath || rawPath, entries: [] });
         }
         return res.status(404).json({ error: 'Directory not found' });
       }
diff --git a/packages/web/server/lib/fs/routes.test.js b/packages/web/server/lib/fs/routes.test.js
index 3d815e78..576c0964 100644
--- a/packages/web/server/lib/fs/routes.test.js
+++ b/packages/web/server/lib/fs/routes.test.js
@@ -635,3 +635,78 @@ describe('fs raw download Content-Disposition', () => {
     expect(cd).toContain("filename*=UTF-8''readme.txt");
   });
 });
+
+describe('fs list symlink path space (issue 2627)', () => {
+  const registerList = (fsPromises) => {
+    const { app, getRoute } = createRouteRegistry();
+    registerFsRoutes(app, {
+      os: { homedir: () => '/home/user' },
+      path: path.posix,
+      fsPromises: {
+        realpath: async (targetPath) => targetPath,
+        ...fsPromises,
+      },
+      spawn: vi.fn(),
+      crypto: { randomUUID: () => 'job-0' },
+      normalizeDirectoryPath: (p) => p,
+      resolveProjectDirectory: async () => ({ directory: '/workspace' }),
+      buildAugmentedPath: () => '/usr/bin',
+      resolveGitBinaryForSpawn: () => 'git',
+      openchamberUserConfigRoot: '/home/user/.config',
+    });
+    return getRoute('GET', '/api/fs/list');
+  };
+
+  const callList = async (handler, query) => {
+    const res = createMockResponse();
+    await handler({ query }, res);
+    return res;
+  };
+
+  it('keeps entry paths in the requested path space when listing through a symlink', async () => {
+    const dirents = [
+      {
+        name: 'src',
+        isDirectory: () => true,
+        isSymbolicLink: () => false,
+        isFile: () => false,
+      },
+      {
+        name: 'README.md',
+        isDirectory: () => false,
+        isSymbolicLink: () => false,
+        isFile: () => true,
+      },
+    ];
+    const fsPromises = {
+      realpath: vi.fn(async (targetPath) => (
+        targetPath === '/workspace/pkg' ? '/real/pkg' : targetPath
+      )),
+      stat: vi.fn(async () => ({ isDirectory: () => true })),
+      readdir: vi.fn(async () => dirents),
+    };
+    const handler = registerList(fsPromises);
+
+    const res = await callList(handler, { path: '/workspace/pkg' });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.body.path).toBe('/workspace/pkg');
+    expect(res.body.entries).toEqual([
+      {
+        name: 'src',
+        path: '/workspace/pkg/src',
+        isDirectory: true,
+        isFile: false,
+        isSymbolicLink: false,
+      },
+      {
+        name: 'README.md',
+        path: '/workspace/pkg/README.md',
+        isDirectory: false,
+        isFile: true,
+        isSymbolicLink: false,
+      },
+    ]);
+    expect(fsPromises.readdir).toHaveBeenCalledWith('/real/pkg', { withFileTypes: true });
+  });
+});

From 359225d36374e3fe3810821aacfc4e18ca1ff424 Mon Sep 17 00:00:00 2001
From: makeittech <serkraser@gmail.com>
Date: Thu, 6 Aug 2026 09:28:31 +0300
Subject: [PATCH 32/57] fix(tasks): harden loop reconciliation against renames
 and malformed files

Review fixes for the markdown loop feature:

- Loop-owned tasks now adopt by loop file path, not task name, so renaming
  a loop (frontmatter name or UI rename) renames the task in place instead
  of leaving a stale duplicate that keeps running the old definition;
  orphan duplicates of the same file are unscheduled.
- Unparseable loop files are reported to the scheduler as
  definition:null entries: a task whose file still exists is kept with its
  last good definition, and only a genuinely removed file unschedules it.
  Transiently malformed files (mid-edit, bad merge) no longer delete tasks
  or their runtime state.
- Adoption preserves UI-only execution fields (goalEnabled, goalTokenBudget,
  permissionAutoAccept, variant) that the portable format does not define.
- DELETE on a loop-sourced task now returns 400 with guidance to remove the
  loop file, instead of being silently undone by the next reconcile.
- Loops default to enabled: false; discovery of repository content never
  auto-executes scheduled sessions unless the file explicitly enables them.

Regression tests for each fix; DOCUMENTATION.md updated.
---
 .../web/server/lib/projects/project-config.js |  55 +++++--
 .../lib/projects/project-config.test.js       | 142 ++++++++++++++++++
 .../lib/scheduled-tasks/DOCUMENTATION.md      |  31 ++--
 .../web/server/lib/scheduled-tasks/loops.js   |  21 ++-
 .../server/lib/scheduled-tasks/loops.test.js  |  37 ++++-
 .../web/server/lib/scheduled-tasks/service.js |  11 ++
 .../lib/scheduled-tasks/service.test.js       |  65 ++++++++
 7 files changed, 334 insertions(+), 28 deletions(-)
 create mode 100644 packages/web/server/lib/scheduled-tasks/service.test.js

diff --git a/packages/web/server/lib/projects/project-config.js b/packages/web/server/lib/projects/project-config.js
index 453d487f..54166695 100644
--- a/packages/web/server/lib/projects/project-config.js
+++ b/packages/web/server/lib/projects/project-config.js
@@ -570,18 +570,27 @@ export const createProjectConfigRuntime = (deps) => {
    * task list.
    *
    * Rules (documented in scheduled-tasks/DOCUMENTATION.md):
-   * - Identity is the task NAME. A loop whose name matches an existing task
-   *   takes that task over: its schedule/execution/enabled are overwritten
-   *   from the file while its id and runtime state are preserved (markdown
-   *   wins on conflict).
+   * - For loop-owned tasks (carrying the `loopFile` marker) identity is the
+   *   LOOP FILE PATH: a loop takes its task over regardless of the task's
+   *   current name, so renaming the loop (`name` field or a UI edit) renames
+   *   the task in place instead of leaving a stale duplicate behind.
+   * - A loop whose name matches a JSON task (no `loopFile`) takes that task
+   *   over: its schedule/execution/enabled are overwritten from the file while
+   *   its id and runtime state are preserved (markdown wins on conflict).
+   *   Execution fields the file format does not define (goalEnabled,
+   *   goalTokenBudget, permissionAutoAccept, variant) are preserved.
    * - A task whose loopFile no longer matches any discovered loop file is
    *   unscheduled (removed). JSON-configured tasks (no loopFile) are never
    *   removed.
+   * - A task whose loop file still exists but is currently unparseable is
+   *   KEPT with its last good definition: only a genuinely removed file
+   *   unschedules a task, so transiently malformed files (mid-edit, bad
+   *   merge) never delete tasks or their runtime state.
    * - Loops with no matching task are created under a deterministic
    *   `loop:<scope>:<name>` id, so runtime state survives restarts.
    * - Malformed definitions are skipped with a warning and never block valid
-   *   loops; the scheduler passes only parsed definitions, and normalization
-   *   failures here are isolated per loop.
+   *   loops; the scheduler passes them as `definition: null` entries, and
+   *   normalization failures here are isolated per loop.
    */
   const reconcileLoopTasks = async (projectID, loops) => {
     return withProjectWriteLock(projectID, async () => {
@@ -591,14 +600,19 @@ export const createProjectConfigRuntime = (deps) => {
 
       const activeLoopFilePaths = new Set();
       const pendingLoops = new Map();
+      const loopsByPath = new Map();
       for (const loop of loops) {
-        if (!loop || !loop.definition || typeof loop.definition !== 'object') {
+        if (!loop || typeof loop.filePath !== 'string' || !loop.filePath) {
           continue;
         }
         activeLoopFilePaths.add(loop.filePath);
-        pendingLoops.set(loop.definition.name, loop);
+        if (loop.definition && typeof loop.definition === 'object') {
+          pendingLoops.set(loop.definition.name, loop);
+          loopsByPath.set(loop.filePath, loop);
+        }
       }
 
+      const consumedLoopPaths = new Set();
       const nextTasks = [];
       for (const task of tasks) {
         if (task.loopFile && !activeLoopFilePaths.has(task.loopFile)) {
@@ -606,11 +620,22 @@ export const createProjectConfigRuntime = (deps) => {
           continue;
         }
 
-        const loop = pendingLoops.get(task.name);
+        // Loop-owned tasks adopt by file path (covers renames of the `name`
+        // field); JSON tasks adopt by name.
+        const loop = task.loopFile
+          ? loopsByPath.get(task.loopFile) || null
+          : pendingLoops.get(task.name) || null;
         if (loop) {
           try {
             const adopted = normalizeTaskForStorage(
-              { ...task, ...loop.definition, loopFile: loop.filePath },
+              {
+                ...task,
+                ...loop.definition,
+                // File-defined execution fields win; UI-only fields the file
+                // format does not define are preserved from the task.
+                execution: { ...task.execution, ...loop.definition.execution },
+                loopFile: loop.filePath,
+              },
               {
                 now,
                 createId: taskIDFactory,
@@ -621,6 +646,10 @@ export const createProjectConfigRuntime = (deps) => {
             );
             nextTasks.push(adopted);
             pendingLoops.delete(loop.definition.name);
+            if (task.loopFile) {
+              consumedLoopPaths.add(task.loopFile);
+              loopsByPath.delete(task.loopFile);
+            }
           } catch (error) {
             console.warn(`[scheduled-tasks] skipped loop ${loop.filePath} for task "${task.name}":`, error?.message ?? error);
             nextTasks.push(task);
@@ -628,6 +657,12 @@ export const createProjectConfigRuntime = (deps) => {
           continue;
         }
 
+        if (task.loopFile && consumedLoopPaths.has(task.loopFile)) {
+          // Orphan duplicate: another task already adopted this loop file
+          // (left over from a rename) — unschedule it.
+          continue;
+        }
+
         nextTasks.push(task);
       }
 
diff --git a/packages/web/server/lib/projects/project-config.test.js b/packages/web/server/lib/projects/project-config.test.js
index 38122c3f..408866c8 100644
--- a/packages/web/server/lib/projects/project-config.test.js
+++ b/packages/web/server/lib/projects/project-config.test.js
@@ -329,4 +329,146 @@ describe('project-config loop reconciliation', () => {
       await cleanup();
     }
   });
+
+  it('renames a loop-sourced task in place when the loop name changes but the file stays', async () => {
+    // Identity for loop-owned tasks is the loop file path: changing the `name`
+    // field (or renaming via the UI) must not leave a stale duplicate running.
+    const { runtime, cleanup } = await createRuntime();
+    try {
+      const first = await runtime.reconcileLoopTasks('project-test', [loop('daily-digest')]);
+      const original = first.find((task) => task.name === 'daily-digest');
+
+      const renamed = await runtime.reconcileLoopTasks('project-test', [{
+        scope: 'project',
+        filePath: '/repo/.agents/loops/daily-digest.md',
+        definition: {
+          name: 'digest',
+          enabled: true,
+          schedule: { kind: 'cron', cron: '0 9 * * *', timezone: 'UTC' },
+          execution: { prompt: 'Loop prompt for digest', providerID: 'openai', modelID: 'gpt-4.1' },
+        },
+      }]);
+
+      expect(renamed).toHaveLength(1);
+      const adopted = renamed[0];
+      expect(adopted.id).toBe(original.id);
+      expect(adopted.name).toBe('digest');
+      expect(adopted.loopFile).toBe('/repo/.agents/loops/daily-digest.md');
+      expect(adopted.execution.prompt).toBe('Loop prompt for digest');
+    } finally {
+      await cleanup();
+    }
+  });
+
+  it('reverts a UI rename of a loop task back to the loop name on reconcile', async () => {
+    const { runtime, cleanup } = await createRuntime();
+    try {
+      await runtime.reconcileLoopTasks('project-test', [loop('daily-digest')]);
+      const created = (await runtime.listScheduledTasks('project-test'))[0];
+
+      // The UI editor renamed the task; loopFile survives the write.
+      await runtime.upsertScheduledTask('project-test', {
+        id: created.id,
+        name: 'renamed-by-ui',
+        enabled: true,
+        schedule: { kind: 'daily', time: '09:30', timezone: 'UTC' },
+        execution: { prompt: 'UI prompt', providerID: 'openai', modelID: 'gpt-4.1' },
+      });
+
+      const after = await runtime.reconcileLoopTasks('project-test', [loop('daily-digest')]);
+      expect(after).toHaveLength(1);
+      expect(after[0].id).toBe(created.id);
+      expect(after[0].name).toBe('daily-digest');
+      expect(after[0].execution.prompt).toBe('Loop prompt for daily-digest');
+    } finally {
+      await cleanup();
+    }
+  });
+
+  it('keeps a loop-sourced task while its file exists but is currently unparseable', async () => {
+    // A transiently malformed file (mid-edit, bad merge) must not delete the
+    // task or its runtime state — only a genuinely removed file unschedules.
+    const { runtime, cleanup } = await createRuntime();
+    try {
+      const first = await runtime.reconcileLoopTasks('project-test', [loop('daily-digest')]);
+      const original = first[0];
+      await runtime.updateScheduledTaskState('project-test', original.id, {
+        nextRunAt: 123456,
+        lastRunAt: 111,
+        lastStatus: 'success',
+      });
+
+      const after = await runtime.reconcileLoopTasks('project-test', [{
+        scope: 'project',
+        filePath: '/repo/.agents/loops/daily-digest.md',
+        definition: null,
+      }]);
+
+      expect(after).toHaveLength(1);
+      expect(after[0].id).toBe(original.id);
+      expect(after[0].name).toBe('daily-digest');
+      expect(after[0].loopFile).toBe('/repo/.agents/loops/daily-digest.md');
+      expect(after[0].schedule.cron).toBe('0 9 * * *');
+      expect(after[0].state.nextRunAt).toBe(123456);
+      expect(after[0].state.lastStatus).toBe('success');
+    } finally {
+      await cleanup();
+    }
+  });
+
+  it('unschedules orphan duplicates of the same loop file', async () => {
+    // Zombie cleanup: two tasks driving one file (e.g. left over from a
+    // rename under the old name-identity rules) — the later one is removed.
+    const { runtime, cleanup } = await createRuntime();
+    try {
+      const first = await runtime.reconcileLoopTasks('project-test', [loop('daily-digest')]);
+      const original = first[0];
+      await runtime.upsertScheduledTask('project-test', {
+        id: 'zombie-copy',
+        name: 'daily-digest-copy',
+        enabled: true,
+        loopFile: '/repo/.agents/loops/daily-digest.md',
+        schedule: { kind: 'daily', time: '09:30', timezone: 'UTC' },
+        execution: { prompt: 'Stale copy', providerID: 'openai', modelID: 'gpt-4.1' },
+      });
+
+      const after = await runtime.reconcileLoopTasks('project-test', [loop('daily-digest')]);
+
+      expect(after).toHaveLength(1);
+      expect(after[0].id).toBe(original.id);
+      expect(after.find((task) => task.id === 'zombie-copy')).toBeUndefined();
+    } finally {
+      await cleanup();
+    }
+  });
+
+  it('preserves UI-only execution fields when adopting a JSON task', async () => {
+    const { runtime, cleanup } = await createRuntime();
+    try {
+      const created = await runtime.upsertScheduledTask('project-test', {
+        name: 'daily-digest',
+        enabled: true,
+        schedule: { kind: 'daily', time: '09:30', timezone: 'UTC' },
+        execution: {
+          prompt: 'JSON prompt',
+          providerID: 'openai',
+          modelID: 'gpt-4.1',
+          variant: 'fast',
+          goalEnabled: true,
+          goalTokenBudget: 20000,
+          permissionAutoAccept: true,
+        },
+      });
+
+      const adopted = await runtime.reconcileLoopTasks('project-test', [loop('daily-digest')]);
+      const task = adopted.find((entry) => entry.id === created.task.id);
+      expect(task.execution.prompt).toBe('Loop prompt for daily-digest');
+      expect(task.execution.variant).toBe('fast');
+      expect(task.execution.goalEnabled).toBe(true);
+      expect(task.execution.goalTokenBudget).toBe(20000);
+      expect(task.execution.permissionAutoAccept).toBe(true);
+    } finally {
+      await cleanup();
+    }
+  });
 });
diff --git a/packages/web/server/lib/scheduled-tasks/DOCUMENTATION.md b/packages/web/server/lib/scheduled-tasks/DOCUMENTATION.md
index 16206a82..5bdba849 100644
--- a/packages/web/server/lib/scheduled-tasks/DOCUMENTATION.md
+++ b/packages/web/server/lib/scheduled-tasks/DOCUMENTATION.md
@@ -50,7 +50,7 @@ Field mapping (model: `packages/ui/src/lib/scheduledTasksApi.ts`):
 |---|---|
 | `name` | `name` (required) |
 | `schedule` | `schedule.kind: "cron"` + `schedule.cron` (required, cron-only in the portable format) |
-| `enabled` | `enabled` (default `true`) |
+| `enabled` | `enabled` (default `false` — a loop only runs when the file explicitly enables it; add `enabled: true` to activate) |
 | `model` | split on the first `/` into `execution.providerID` / `execution.modelID` (required) |
 | `agent` | `execution.agent` (optional) |
 | `timezone` | `schedule.timezone` (optional, IANA; defaults to the server zone) |
@@ -67,24 +67,37 @@ the project config state store.
 `projectConfigRuntime.reconcileLoopTasks(projectID, loops)` runs inside the
 project write lock on every `syncProject` when the project path is known:
 
-- **Identity is the task name.** A loop whose name matches an existing task
-  takes that task over: its schedule/execution/enabled are overwritten from the
-  file while the task's `id` and runtime `state` are preserved (markdown wins
-  on conflict with JSON-configured tasks).
+- **Identity.** For loop-owned tasks (carrying the `loopFile` marker) identity
+  is the loop file path: a loop takes its task over regardless of the task's
+  current name, so renaming the loop (the `name` field, or a UI rename) renames
+  the task in place instead of leaving a stale duplicate behind. A loop whose
+  name matches a JSON task (no `loopFile`) takes that task over instead: its
+  schedule/execution/enabled are overwritten from the file while the task's
+  `id` and runtime `state` are preserved (markdown wins on conflict).
+- **UI-only fields survive adoption.** Execution fields the file format does
+  not define (`goalEnabled`, `goalTokenBudget`, `permissionAutoAccept`,
+  `variant`) are preserved from the task when a loop adopts it; only fields the
+  file defines are re-applied.
 - **Deletion.** A task carrying the `loopFile` marker whose loop file is no
   longer discovered (removed or renamed) is unscheduled (removed from the
   config). The marker is persisted in the config file, so removal is detected
   across restarts. JSON-configured tasks without the marker are never removed.
+  A task whose loop file still exists but is currently unparseable is KEPT with
+  its last good definition — a transiently malformed file (mid-edit, bad merge)
+  never deletes a task or its runtime state.
 - **Creation.** Loops without a matching task are created under a deterministic
-  `loop:<scope>:<name>` id so runtime state survives restarts.
+  `loop:<scope>:<name>` id so runtime state survives restarts. At most one task
+  is driven per loop file; orphan duplicates of the same file are unscheduled.
 - **Scope precedence.** Project-scope loops shadow user-scope loops with the
   same name; among project files the nearest ancestor wins.
 - **Malformed files** (missing `name`/`schedule`/`model`/body, invalid cron,
-  unreadable) are skipped with a warning and never block valid loops in the
-  same or other scopes.
+  unreadable) are reported to the scheduler as `definition: null` entries and
+  warned about; they never block valid loops in the same or other scopes.
 - **UI edits** to a loop-sourced task are preserved in the config but the loop
   file remains authoritative: the next reconciliation re-applies the file's
-  definition (including `enabled`). Use `enabled: false` in the file to disable.
+  definition (including `enabled`). Use `enabled: false` in the file to
+  disable. Deleting a loop-sourced task through the API is rejected with a 400 —
+  the loop file is the removal surface.
 
 ## Public exports (runtime.js)
 
diff --git a/packages/web/server/lib/scheduled-tasks/loops.js b/packages/web/server/lib/scheduled-tasks/loops.js
index 2dbcf4c2..1fd71be7 100644
--- a/packages/web/server/lib/scheduled-tasks/loops.js
+++ b/packages/web/server/lib/scheduled-tasks/loops.js
@@ -21,7 +21,9 @@
  * Field mapping (see packages/ui/src/lib/scheduledTasksApi.ts):
  *   name     -> task.name
  *   schedule -> task.schedule.kind "cron" + task.schedule.cron
- *   enabled  -> task.enabled (default true)
+ *   enabled  -> task.enabled (default false — loops only run when the file
+ *               explicitly enables them, so discovery never auto-executes
+ *               repository content)
  *   model    -> split into task.execution.providerID / task.execution.modelID
  *   agent    -> task.execution.agent (optional)
  *   timezone -> task.schedule.timezone (optional, defaults to the server zone)
@@ -116,7 +118,7 @@ export const parseLoopDefinition = (filePath) => {
 
   return {
     name,
-    enabled: typeof frontmatter.enabled === 'boolean' ? frontmatter.enabled : true,
+    enabled: typeof frontmatter.enabled === 'boolean' ? frontmatter.enabled : false,
     schedule: {
       kind: 'cron',
       cron,
@@ -170,13 +172,21 @@ export const discoverLoopFiles = (projectPath) => {
 /**
  * Discover and parse all loops for a project. Project-scope loops shadow
  * user-scope loops with the same name; among project files the nearest
- * ancestor wins. Malformed files are skipped with a warning.
+ * ancestor wins.
+ *
+ * Unparseable files are reported as `{ scope, filePath, definition: null }`
+ * entries instead of being dropped: the scheduler must distinguish "file is
+ * gone" (unschedule its task) from "file exists but is currently malformed"
+ * (keep its task with the last good definition until the file is fixed).
+ * Malformed files never block valid ones in the same or other scopes.
  */
 export const discoverLoops = (projectPath) => {
   const byName = new Map();
+  const loops = [];
   for (const { filePath, scope } of discoverLoopFiles(projectPath)) {
     const definition = parseLoopDefinition(filePath);
     if (!definition) {
+      loops.push({ scope, filePath, definition: null });
       continue;
     }
     const existing = byName.get(definition.name);
@@ -185,5 +195,8 @@ export const discoverLoops = (projectPath) => {
     }
     byName.set(definition.name, { scope, filePath, definition });
   }
-  return [...byName.values()];
+  for (const entry of byName.values()) {
+    loops.push(entry);
+  }
+  return loops;
 };
diff --git a/packages/web/server/lib/scheduled-tasks/loops.test.js b/packages/web/server/lib/scheduled-tasks/loops.test.js
index ac204392..7281adda 100644
--- a/packages/web/server/lib/scheduled-tasks/loops.test.js
+++ b/packages/web/server/lib/scheduled-tasks/loops.test.js
@@ -73,13 +73,13 @@ Run weekly checks.
 
       expect(definition.execution.providerID).toBe('openai');
       expect(definition.execution.modelID).toBe('gpt-5');
-      expect(definition.enabled).toBe(true);
+      expect(definition.enabled).toBe(false);
     } finally {
       await cleanup();
     }
   });
 
-  it('defaults enabled to true and omits optional fields', async () => {
+  it('defaults enabled to false and omits optional fields', async () => {
     const { projectPath, cleanup } = await createProject();
     try {
       const filePath = path.join(projectPath, 'loop.md');
@@ -87,13 +87,14 @@ Run weekly checks.
 name: minimal
 schedule: "*/30 * * * *"
 model: openai/gpt-5
-enabled: false
 ---
 Run every half hour.
 `, 'utf8');
 
       const definition = parseLoopDefinition(filePath);
 
+      // Loops only run when the file explicitly enables them: discovery of
+      // repository content must never auto-execute scheduled sessions.
       expect(definition.enabled).toBe(false);
       expect(definition.schedule).toEqual({ kind: 'cron', cron: '*/30 * * * *' });
       expect(definition.execution.agent).toBeUndefined();
@@ -102,6 +103,25 @@ Run every half hour.
     }
   });
 
+  it('honors an explicit enabled: true in the frontmatter', async () => {
+    const { projectPath, cleanup } = await createProject();
+    try {
+      const filePath = path.join(projectPath, 'loop.md');
+      await writeFile(filePath, `---
+name: explicit-enabled
+schedule: "*/30 * * * *"
+model: openai/gpt-5
+enabled: true
+---
+Run every half hour.
+`, 'utf8');
+
+      expect(parseLoopDefinition(filePath).enabled).toBe(true);
+    } finally {
+      await cleanup();
+    }
+  });
+
   it('returns null for files missing required frontmatter fields', async () => {
     const { projectPath, cleanup } = await createProject();
     try {
@@ -272,7 +292,7 @@ Project version.
     }
   });
 
-  it('skips malformed files without blocking valid ones', async () => {
+  it('reports malformed files as unparsed entries without blocking valid ones', async () => {
     const { projectPath, cleanup } = await createProject();
     try {
       await writeLoop(projectPath, 'bad.md', `---
@@ -292,7 +312,14 @@ Valid.
       try {
         const loops = discoverLoops(projectPath);
 
-        expect(loops.map((loop) => loop.definition.name)).toEqual(['good']);
+        // The malformed file stays visible as a `definition: null` entry so
+        // the scheduler can keep its task alive while the file is fixed.
+        const bad = loops.find((loop) => loop.filePath.endsWith(path.join('.agents', 'loops', 'bad.md')));
+        expect(bad.definition).toBeNull();
+        expect(bad.scope).toBe('project');
+
+        const good = loops.find((loop) => loop.filePath.endsWith(path.join('.agents', 'loops', 'good.md')));
+        expect(good.definition.name).toBe('good');
         expect(warn).toHaveBeenCalled();
       } finally {
         warn.mockRestore();
diff --git a/packages/web/server/lib/scheduled-tasks/service.js b/packages/web/server/lib/scheduled-tasks/service.js
index 7d44f4e8..33d69f7d 100644
--- a/packages/web/server/lib/scheduled-tasks/service.js
+++ b/packages/web/server/lib/scheduled-tasks/service.js
@@ -78,6 +78,17 @@ export const createScheduledTaskService = (dependencies) => {
     await findProjectByID(projectID);
     const normalizedTaskID = asNonEmptyString(taskID);
     if (!normalizedTaskID) throw new OpenChamberControlError('taskId is required', 400);
+    const current = await projectConfigRuntime.listScheduledTasks(projectID);
+    const existing = current.find((task) => task.id === normalizedTaskID) || null;
+    if (existing?.loopFile) {
+      // Loop tasks are owned by their `.agents/loops` markdown file: deleting
+      // the JSON row would be silently undone by the next reconcile. The file
+      // itself is the removal surface.
+      throw new OpenChamberControlError(
+        'Loop task is managed by its .agents/loops markdown file; delete the file to remove the task',
+        400,
+      );
+    }
     const result = await projectConfigRuntime.deleteScheduledTask(projectID, normalizedTaskID);
     if (!result.deleted) throw new OpenChamberControlError('Task not found', 404);
     await scheduledTasksRuntime.syncProject(projectID);
diff --git a/packages/web/server/lib/scheduled-tasks/service.test.js b/packages/web/server/lib/scheduled-tasks/service.test.js
new file mode 100644
index 00000000..07d6bf70
--- /dev/null
+++ b/packages/web/server/lib/scheduled-tasks/service.test.js
@@ -0,0 +1,65 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createScheduledTaskService } from './service.js';
+
+const createService = (overrides = {}) => {
+  const projectConfigRuntime = {
+    listScheduledTasks: vi.fn(async () => []),
+    deleteScheduledTask: vi.fn(async () => ({ deleted: true, tasks: [] })),
+    ...(overrides.projectConfigRuntime || {}),
+  };
+  const scheduledTasksRuntime = {
+    syncProject: vi.fn(async () => []),
+    ...(overrides.scheduledTasksRuntime || {}),
+  };
+  const service = createScheduledTaskService({
+    readSettingsFromDiskMigrated: async () => ({
+      projects: [{ id: 'project-test', path: '/repo' }],
+    }),
+    sanitizeProjects: (projects) => projects,
+    projectConfigRuntime,
+    scheduledTasksRuntime,
+  });
+  return { service, projectConfigRuntime, scheduledTasksRuntime };
+};
+
+const loopTask = {
+  id: 'loop:project:daily-digest',
+  name: 'daily-digest',
+  enabled: true,
+  loopFile: '/repo/.agents/loops/daily-digest.md',
+  schedule: { kind: 'cron', cron: '0 9 * * *', timezone: 'UTC' },
+  execution: { prompt: 'digest', providerID: 'openai', modelID: 'gpt-4.1' },
+};
+
+describe('scheduled-task service remove', () => {
+  it('rejects deleting a loop-sourced task without touching storage', async () => {
+    const { service, projectConfigRuntime, scheduledTasksRuntime } = createService({
+      projectConfigRuntime: {
+        listScheduledTasks: vi.fn(async () => [loopTask]),
+      },
+    });
+
+    await expect(service.remove('project-test', loopTask.id)).rejects.toMatchObject({
+      statusCode: 400,
+      message: expect.stringContaining('delete the file to remove the task'),
+    });
+    expect(projectConfigRuntime.deleteScheduledTask).not.toHaveBeenCalled();
+    expect(scheduledTasksRuntime.syncProject).not.toHaveBeenCalled();
+  });
+
+  it('deletes JSON-configured tasks normally', async () => {
+    const jsonTask = { ...loopTask, id: 'json-task', loopFile: undefined };
+    const { service, projectConfigRuntime, scheduledTasksRuntime } = createService({
+      projectConfigRuntime: {
+        listScheduledTasks: vi.fn(async () => [jsonTask]),
+        deleteScheduledTask: vi.fn(async () => ({ deleted: true, tasks: [] })),
+      },
+    });
+
+    const tasks = await service.remove('project-test', jsonTask.id);
+
+    expect(projectConfigRuntime.deleteScheduledTask).toHaveBeenCalledWith('project-test', jsonTask.id);
+    expect(scheduledTasksRuntime.syncProject).toHaveBeenCalled();
+    expect(Array.isArray(tasks)).toBe(true);
+  });
+});

From 59a6c1b70db723431e1a5771f7e6165e7045453f Mon Sep 17 00:00:00 2001
From: makeittech <serkraser@gmail.com>
Date: Thu, 6 Aug 2026 09:38:18 +0300
Subject: [PATCH 33/57] fix(tasks): guard loop name length and surface loop
 ownership in the UI

Review follow-up:

- Reject loop files whose frontmatter name exceeds MAX_TASK_NAME_LENGTH
  (80): task names are clamped at storage time, so a raw name longer than
  the limit could never match the stored task identity. The file is treated
  as malformed (definition: null) instead of creating an unreachable
  definition; MAX_TASK_NAME_LENGTH is now exported from project-config.js
  and shared with loops.js.
- Surface loop-sourced tasks in the scheduled-tasks dialog: tasks carrying
  loopFile show a 'Managed by loop file <path>' note, and the enable
  toggle / edit / delete actions are disabled with an explanatory tooltip,
  since the file remains authoritative and would revert any such change.
  run-now stays available. New locale keys added to all 11 message files
  (i18n parity test enforces exact key sets).
- ScheduledTask type gains an optional loopFile field (additive, unknown
  to older clients).
---
 .../session/ScheduledTasksDialog.tsx          | 25 ++++++++++++++---
 packages/ui/src/lib/i18n/messages/de.ts       |  3 +++
 packages/ui/src/lib/i18n/messages/en.ts       |  3 +++
 packages/ui/src/lib/i18n/messages/es.ts       |  3 +++
 packages/ui/src/lib/i18n/messages/fr.ts       |  3 +++
 packages/ui/src/lib/i18n/messages/ja.ts       |  3 +++
 packages/ui/src/lib/i18n/messages/ko.ts       |  3 +++
 packages/ui/src/lib/i18n/messages/pl.ts       |  3 +++
 packages/ui/src/lib/i18n/messages/pt-BR.ts    |  3 +++
 packages/ui/src/lib/i18n/messages/uk.ts       |  3 +++
 packages/ui/src/lib/i18n/messages/zh-CN.ts    |  3 +++
 packages/ui/src/lib/i18n/messages/zh-TW.ts    |  3 +++
 packages/ui/src/lib/scheduledTasksApi.ts      |  3 +++
 .../web/server/lib/projects/project-config.js |  2 +-
 .../lib/scheduled-tasks/DOCUMENTATION.md      |  6 +++--
 .../web/server/lib/scheduled-tasks/loops.js   |  7 +++++
 .../server/lib/scheduled-tasks/loops.test.js  | 27 +++++++++++++++++++
 17 files changed, 96 insertions(+), 7 deletions(-)

diff --git a/packages/ui/src/components/session/ScheduledTasksDialog.tsx b/packages/ui/src/components/session/ScheduledTasksDialog.tsx
index c75e677e..6590e67b 100644
--- a/packages/ui/src/components/session/ScheduledTasksDialog.tsx
+++ b/packages/ui/src/components/session/ScheduledTasksDialog.tsx
@@ -463,6 +463,14 @@ export function ScheduledTasksDialog() {
                   <div className="typography-micro truncate text-muted-foreground">
                     {formatSchedule(task, t)}
                   </div>
+                  {task.loopFile ? (
+                    <div
+                      className="typography-micro truncate text-muted-foreground/70"
+                      title={task.loopFile}
+                    >
+                      {t('sessions.scheduledTasks.dialog.loopFile.note', { file: task.loopFile })}
+                    </div>
+                  ) : null}
                 </div>
 
                 <div className="mt-3 flex flex-wrap items-center gap-x-5 gap-y-1 typography-micro text-muted-foreground">
@@ -525,8 +533,11 @@ export function ScheduledTasksDialog() {
                     className={cn(
                       'inline-flex cursor-pointer items-center gap-2 typography-micro font-medium',
                       task.enabled ? 'text-foreground' : 'text-muted-foreground',
-                      isBusy && 'cursor-not-allowed opacity-50',
+                      (isBusy || task.loopFile) && 'cursor-not-allowed opacity-50',
                     )}
+                    title={task.loopFile
+                      ? t('sessions.scheduledTasks.dialog.loopFile.toggleDisabled')
+                      : undefined}
                   >
                     <Checkbox
                       checked={task.enabled}
@@ -534,7 +545,7 @@ export function ScheduledTasksDialog() {
                       ariaLabel={task.enabled
                         ? t('sessions.scheduledTasks.dialog.taskToggle.pauseAria', { taskName: task.name })
                         : t('sessions.scheduledTasks.dialog.taskToggle.enableAria', { taskName: task.name })}
-                      disabled={isBusy}
+                      disabled={isBusy || Boolean(task.loopFile)}
                     />
                     {task.enabled ? t('sessions.scheduledTasks.dialog.taskToggle.enabled') : t('sessions.scheduledTasks.dialog.taskToggle.paused')}
                   </label>
@@ -555,7 +566,10 @@ export function ScheduledTasksDialog() {
                         setEditorTask(task);
                         setEditorOpen(true);
                       }}
-                      disabled={isBusy}
+                      disabled={isBusy || Boolean(task.loopFile)}
+                      title={task.loopFile
+                        ? t('sessions.scheduledTasks.dialog.loopFile.actionsDisabled')
+                        : undefined}
                       aria-label={t('sessions.scheduledTasks.dialog.actions.editAria', { taskName: task.name })}
                     >
                       <Icon name="edit-2" className="h-4 w-4" /> {t('sessions.scheduledTasks.dialog.actions.edit')}
@@ -564,7 +578,10 @@ export function ScheduledTasksDialog() {
                       variant="destructive"
                       size="sm"
                       onClick={() => void handleDeleteTask(task)}
-                      disabled={isBusy}
+                      disabled={isBusy || Boolean(task.loopFile)}
+                      title={task.loopFile
+                        ? t('sessions.scheduledTasks.dialog.loopFile.actionsDisabled')
+                        : undefined}
                       aria-label={t('sessions.scheduledTasks.dialog.actions.deleteAria', { taskName: task.name })}
                     >
                       <Icon name="delete-bin" className="h-4 w-4" />
diff --git a/packages/ui/src/lib/i18n/messages/de.ts b/packages/ui/src/lib/i18n/messages/de.ts
index 57a22de2..0190f560 100644
--- a/packages/ui/src/lib/i18n/messages/de.ts
+++ b/packages/ui/src/lib/i18n/messages/de.ts
@@ -248,6 +248,9 @@ export const dict = {
   'sessions.scheduledTasks.dialog.taskToggle.pauseAria': '{taskName} pausieren',
   'sessions.scheduledTasks.dialog.taskToggle.enabled': 'Aktiviert',
   'sessions.scheduledTasks.dialog.taskToggle.paused': 'Pausiert',
+  'sessions.scheduledTasks.dialog.loopFile.note': 'Von Loop-Datei verwaltet {file}',
+  'sessions.scheduledTasks.dialog.loopFile.toggleDisabled': 'Aktiviert wird durch die Loop-Datei gesteuert; setze enabled im Markdown-Frontmatter',
+  'sessions.scheduledTasks.dialog.loopFile.actionsDisabled': 'Loop-Aufgaben werden in ihrer .agents/loops-Markdown-Datei konfiguriert',
   'sessions.scheduledTasks.editor.title.edit': 'Geplante Aufgabe bearbeiten',
   'sessions.scheduledTasks.editor.title.new': 'Neue geplante Aufgabe',
   'sessions.scheduledTasks.editor.description': 'Konfigurieren Sie eine serverseitige Aufgabe, die eine neue Sitzung erstellt und eine Eingabeaufforderung sendet.',
diff --git a/packages/ui/src/lib/i18n/messages/en.ts b/packages/ui/src/lib/i18n/messages/en.ts
index c77d6a07..5d0742a0 100644
--- a/packages/ui/src/lib/i18n/messages/en.ts
+++ b/packages/ui/src/lib/i18n/messages/en.ts
@@ -268,6 +268,9 @@ export const dict = {
   'sessions.scheduledTasks.dialog.taskToggle.pauseAria': 'Pause {taskName}',
   'sessions.scheduledTasks.dialog.taskToggle.enabled': 'Enabled',
   'sessions.scheduledTasks.dialog.taskToggle.paused': 'Paused',
+  'sessions.scheduledTasks.dialog.loopFile.note': 'Managed by loop file {file}',
+  'sessions.scheduledTasks.dialog.loopFile.toggleDisabled': 'Enabled is controlled by the loop file; set enabled in the markdown frontmatter',
+  'sessions.scheduledTasks.dialog.loopFile.actionsDisabled': 'Loop tasks are configured in their .agents/loops markdown file',
   'sessions.scheduledTasks.editor.title.edit': 'Edit scheduled task',
   'sessions.scheduledTasks.editor.title.new': 'New scheduled task',
   'sessions.scheduledTasks.editor.description': 'Configure a server-side task that creates a new session and sends a prompt.',
diff --git a/packages/ui/src/lib/i18n/messages/es.ts b/packages/ui/src/lib/i18n/messages/es.ts
index 72985914..9d97a182 100644
--- a/packages/ui/src/lib/i18n/messages/es.ts
+++ b/packages/ui/src/lib/i18n/messages/es.ts
@@ -269,6 +269,9 @@ export const dict: Record<I18nKey, string> = {
   "sessions.scheduledTasks.dialog.taskToggle.pauseAria": "Pausar {taskName}",
   "sessions.scheduledTasks.dialog.taskToggle.enabled": "Habilitado",
   "sessions.scheduledTasks.dialog.taskToggle.paused": "Pausado",
+  'sessions.scheduledTasks.dialog.loopFile.note': 'Gestionada por el archivo de bucle {file}',
+  'sessions.scheduledTasks.dialog.loopFile.toggleDisabled': 'La activación la controla el archivo de bucle; establece enabled en el frontmatter de Markdown',
+  'sessions.scheduledTasks.dialog.loopFile.actionsDisabled': 'Las tareas de bucle se configuran en su archivo Markdown .agents/loops',
   "sessions.scheduledTasks.editor.title.edit": "Editar tarea programada",
   "sessions.scheduledTasks.editor.title.new": "Nueva tarea programada",
   "sessions.scheduledTasks.editor.description": "Configura una tarea del lado del servidor que crea una nueva sesión y envía un prompt.",
diff --git a/packages/ui/src/lib/i18n/messages/fr.ts b/packages/ui/src/lib/i18n/messages/fr.ts
index 986a4cd4..5d40c830 100644
--- a/packages/ui/src/lib/i18n/messages/fr.ts
+++ b/packages/ui/src/lib/i18n/messages/fr.ts
@@ -105,6 +105,9 @@ export const dict = {
   'sessions.scheduledTasks.dialog.taskToggle.pauseAria': 'Pause {taskName}',
   'sessions.scheduledTasks.dialog.taskToggle.enabled': 'Activé',
   'sessions.scheduledTasks.dialog.taskToggle.paused': 'En pause',
+  'sessions.scheduledTasks.dialog.loopFile.note': 'Gérée par le fichier de boucle {file}',
+  'sessions.scheduledTasks.dialog.loopFile.toggleDisabled': "L'activation est contrôlée par le fichier de boucle ; définissez enabled dans le frontmatter Markdown",
+  'sessions.scheduledTasks.dialog.loopFile.actionsDisabled': 'Les tâches de boucle sont configurées dans leur fichier Markdown .agents/loops',
   'sessions.scheduledTasks.editor.title.edit': 'Modifier une tâche planifiée',
   'sessions.scheduledTasks.editor.title.new': 'Nouvelle tâche planifiée',
   'sessions.scheduledTasks.editor.description': 'Configurez une tâche côté serveur qui crée une nouvelle session et envoie un prompt.',
diff --git a/packages/ui/src/lib/i18n/messages/ja.ts b/packages/ui/src/lib/i18n/messages/ja.ts
index 0f4da4e7..352c6727 100644
--- a/packages/ui/src/lib/i18n/messages/ja.ts
+++ b/packages/ui/src/lib/i18n/messages/ja.ts
@@ -269,6 +269,9 @@ export const dict: Record<I18nKey, string> = {
   'sessions.scheduledTasks.dialog.taskToggle.pauseAria': '{taskName}を一時停止',
   'sessions.scheduledTasks.dialog.taskToggle.enabled': '有効',
   'sessions.scheduledTasks.dialog.taskToggle.paused': '一時停止中',
+  'sessions.scheduledTasks.dialog.loopFile.note': 'ループファイル {file} によって管理',
+  'sessions.scheduledTasks.dialog.loopFile.toggleDisabled': '有効状態はループファイルが制御します。Markdown フロントマターで enabled を設定してください',
+  'sessions.scheduledTasks.dialog.loopFile.actionsDisabled': 'ループタスクは .agents/loops の Markdown ファイルで設定します',
   'sessions.scheduledTasks.editor.title.edit': 'スケジュールタスクを編集',
   'sessions.scheduledTasks.editor.title.new': '新しいスケジュールタスク',
   'sessions.scheduledTasks.editor.description': '新しいセッションを作成しプロンプトを送信するサーバーサイドタスクを設定します。',
diff --git a/packages/ui/src/lib/i18n/messages/ko.ts b/packages/ui/src/lib/i18n/messages/ko.ts
index 0f09fba2..5ce56da8 100644
--- a/packages/ui/src/lib/i18n/messages/ko.ts
+++ b/packages/ui/src/lib/i18n/messages/ko.ts
@@ -269,6 +269,9 @@ export const dict: Record<I18nKey, string> = {
   'sessions.scheduledTasks.dialog.taskToggle.pauseAria': '{taskName} 일시 중지',
   'sessions.scheduledTasks.dialog.taskToggle.enabled': '활성화됨',
   'sessions.scheduledTasks.dialog.taskToggle.paused': '일시 중지됨',
+  'sessions.scheduledTasks.dialog.loopFile.note': '루프 파일에서 관리됨: {file}',
+  'sessions.scheduledTasks.dialog.loopFile.toggleDisabled': '활성화 여부는 루프 파일이 제어합니다. Markdown frontmatter에서 enabled를 설정하세요',
+  'sessions.scheduledTasks.dialog.loopFile.actionsDisabled': '루프 작업은 .agents/loops Markdown 파일에서 구성합니다',
   'sessions.scheduledTasks.editor.title.edit': '예약 작업 편집',
   'sessions.scheduledTasks.editor.title.new': '새 예약 작업',
   'sessions.scheduledTasks.editor.description': '새 세션을 만들고 프롬프트를 보내는 서버 작업을 설정합니다.',
diff --git a/packages/ui/src/lib/i18n/messages/pl.ts b/packages/ui/src/lib/i18n/messages/pl.ts
index 12f727b1..06c5aa7f 100644
--- a/packages/ui/src/lib/i18n/messages/pl.ts
+++ b/packages/ui/src/lib/i18n/messages/pl.ts
@@ -396,6 +396,9 @@ export const dict: Record<I18nKey, string> = {
   'sessions.scheduledTasks.dialog.taskToggle.pauseAria': 'Wstrzymaj {taskName}',
   'sessions.scheduledTasks.dialog.taskToggle.enabled': 'Włączone',
   'sessions.scheduledTasks.dialog.taskToggle.paused': 'Wstrzymane',
+  'sessions.scheduledTasks.dialog.loopFile.note': 'Zarządzane przez plik pętli {file}',
+  'sessions.scheduledTasks.dialog.loopFile.toggleDisabled': 'Włączenie jest kontrolowane przez plik pętli; ustaw enabled w frontmatterze Markdown',
+  'sessions.scheduledTasks.dialog.loopFile.actionsDisabled': 'Zadania pętli są konfigurowane w pliku Markdown .agents/loops',
   'sessions.scheduledTasks.editor.title.edit': 'Edytuj zaplanowane zadanie',
   'sessions.scheduledTasks.editor.title.new': 'Nowe zaplanowane zadanie',
   'sessions.scheduledTasks.editor.description': 'Skonfiguruj zadanie po stronie serwera, które tworzy nową sesję i wysyła prompt.',
diff --git a/packages/ui/src/lib/i18n/messages/pt-BR.ts b/packages/ui/src/lib/i18n/messages/pt-BR.ts
index 10dd7709..b33b7976 100644
--- a/packages/ui/src/lib/i18n/messages/pt-BR.ts
+++ b/packages/ui/src/lib/i18n/messages/pt-BR.ts
@@ -269,6 +269,9 @@ export const dict: Record<I18nKey, string> = {
   "sessions.scheduledTasks.dialog.taskToggle.pauseAria": "Pausar {taskName}",
   "sessions.scheduledTasks.dialog.taskToggle.enabled": "Ativado",
   "sessions.scheduledTasks.dialog.taskToggle.paused": "Pausado",
+  'sessions.scheduledTasks.dialog.loopFile.note': 'Gerenciada pelo arquivo de loop {file}',
+  'sessions.scheduledTasks.dialog.loopFile.toggleDisabled': 'A ativação é controlada pelo arquivo de loop; defina enabled no frontmatter Markdown',
+  'sessions.scheduledTasks.dialog.loopFile.actionsDisabled': 'Tarefas de loop são configuradas no arquivo Markdown .agents/loops',
   "sessions.scheduledTasks.editor.title.edit": "Editar tarefa agendada",
   "sessions.scheduledTasks.editor.title.new": "Nova tarefa agendada",
   "sessions.scheduledTasks.editor.description": "Configure uma tarefa do lado do servidor que cria uma nova sessão e envia um prompt.",
diff --git a/packages/ui/src/lib/i18n/messages/uk.ts b/packages/ui/src/lib/i18n/messages/uk.ts
index dd52bcb9..4b389c8d 100644
--- a/packages/ui/src/lib/i18n/messages/uk.ts
+++ b/packages/ui/src/lib/i18n/messages/uk.ts
@@ -269,6 +269,9 @@ export const dict: Record<I18nKey, string> = {
   "sessions.scheduledTasks.dialog.taskToggle.pauseAria": "Призупинити {taskName}",
   "sessions.scheduledTasks.dialog.taskToggle.enabled": "Увімкнено",
   "sessions.scheduledTasks.dialog.taskToggle.paused": "Призупинено",
+  'sessions.scheduledTasks.dialog.loopFile.note': 'Керується файлом циклу {file}',
+  'sessions.scheduledTasks.dialog.loopFile.toggleDisabled': 'Активність контролюється файлом циклу; встановіть enabled у frontmatter Markdown',
+  'sessions.scheduledTasks.dialog.loopFile.actionsDisabled': 'Завдання циклів налаштовуються у файлі Markdown .agents/loops',
   "sessions.scheduledTasks.editor.title.edit": "Редагувати заплановане завдання",
   "sessions.scheduledTasks.editor.title.new": "Нове заплановане завдання",
   "sessions.scheduledTasks.editor.description": "Налаштувати завдання на стороні сервера, яке створює нову сесію і надсилає запит.",
diff --git a/packages/ui/src/lib/i18n/messages/zh-CN.ts b/packages/ui/src/lib/i18n/messages/zh-CN.ts
index 35de2c9c..057e6637 100644
--- a/packages/ui/src/lib/i18n/messages/zh-CN.ts
+++ b/packages/ui/src/lib/i18n/messages/zh-CN.ts
@@ -269,6 +269,9 @@ export const dict: Record<I18nKey, string> = {
   'sessions.scheduledTasks.dialog.taskToggle.pauseAria': '暂停 {taskName}',
   'sessions.scheduledTasks.dialog.taskToggle.enabled': '已启用',
   'sessions.scheduledTasks.dialog.taskToggle.paused': '已暂停',
+  'sessions.scheduledTasks.dialog.loopFile.note': '由循环文件 {file} 管理',
+  'sessions.scheduledTasks.dialog.loopFile.toggleDisabled': '启用状态由循环文件控制；请在 Markdown frontmatter 中设置 enabled',
+  'sessions.scheduledTasks.dialog.loopFile.actionsDisabled': '循环任务在其 .agents/loops Markdown 文件中配置',
   'sessions.scheduledTasks.editor.title.edit': '编辑计划任务',
   'sessions.scheduledTasks.editor.title.new': '新建计划任务',
   'sessions.scheduledTasks.editor.description': '配置一个服务端任务，用于创建新会话并发送提示词。',
diff --git a/packages/ui/src/lib/i18n/messages/zh-TW.ts b/packages/ui/src/lib/i18n/messages/zh-TW.ts
index 6641606b..7c98d160 100644
--- a/packages/ui/src/lib/i18n/messages/zh-TW.ts
+++ b/packages/ui/src/lib/i18n/messages/zh-TW.ts
@@ -282,6 +282,9 @@ export const dict: Record<I18nKey, string> = {
   'sessions.scheduledTasks.dialog.taskToggle.pauseAria': '暫停 {taskName}',
   'sessions.scheduledTasks.dialog.taskToggle.enabled': '已啟用',
   'sessions.scheduledTasks.dialog.taskToggle.paused': '已暫停',
+  'sessions.scheduledTasks.dialog.loopFile.note': '由迴圈檔案 {file} 管理',
+  'sessions.scheduledTasks.dialog.loopFile.toggleDisabled': '啟用狀態由迴圈檔案控制；請在 Markdown frontmatter 中設定 enabled',
+  'sessions.scheduledTasks.dialog.loopFile.actionsDisabled': '迴圈任務在其 .agents/loops Markdown 檔案中設定',
   'sessions.scheduledTasks.editor.title.edit': '編輯排程任務',
   'sessions.scheduledTasks.editor.title.new': '新增排程任務',
   'sessions.scheduledTasks.editor.description': '設定一個伺服器端任務，用於建立新會話並傳送提示詞。',
diff --git a/packages/ui/src/lib/scheduledTasksApi.ts b/packages/ui/src/lib/scheduledTasksApi.ts
index 8b215d64..c7c4aeb1 100644
--- a/packages/ui/src/lib/scheduledTasksApi.ts
+++ b/packages/ui/src/lib/scheduledTasksApi.ts
@@ -6,6 +6,9 @@ export type ScheduledTask = {
   id: string;
   name: string;
   enabled: boolean;
+  /** Absolute path of the `.agents/loops/*.md` file driving this task, when
+   *  any. Present only for loop-sourced tasks; unknown to older clients. */
+  loopFile?: string;
   schedule: {
     kind: 'daily' | 'weekly' | 'once' | 'cron';
     times?: string[];
diff --git a/packages/web/server/lib/projects/project-config.js b/packages/web/server/lib/projects/project-config.js
index 54166695..ab92383e 100644
--- a/packages/web/server/lib/projects/project-config.js
+++ b/packages/web/server/lib/projects/project-config.js
@@ -2,7 +2,7 @@ import { DateTime, IANAZone } from 'luxon';
 import parser from 'cron-parser';
 
 const PROJECT_CONFIG_VERSION = 1;
-const MAX_TASK_NAME_LENGTH = 80;
+export const MAX_TASK_NAME_LENGTH = 80;
 const MAX_TASK_PROMPT_LENGTH = 20_000;
 const MAX_CRON_LENGTH = 200;
 const MAX_LAST_ERROR_LENGTH = 2_000;
diff --git a/packages/web/server/lib/scheduled-tasks/DOCUMENTATION.md b/packages/web/server/lib/scheduled-tasks/DOCUMENTATION.md
index 5bdba849..4de46ab5 100644
--- a/packages/web/server/lib/scheduled-tasks/DOCUMENTATION.md
+++ b/packages/web/server/lib/scheduled-tasks/DOCUMENTATION.md
@@ -48,7 +48,7 @@ Field mapping (model: `packages/ui/src/lib/scheduledTasksApi.ts`):
 
 | Frontmatter | Task field |
 |---|---|
-| `name` | `name` (required) |
+| `name` | `name` (required, max 80 characters — longer names are rejected as malformed) |
 | `schedule` | `schedule.kind: "cron"` + `schedule.cron` (required, cron-only in the portable format) |
 | `enabled` | `enabled` (default `false` — a loop only runs when the file explicitly enables it; add `enabled: true` to activate) |
 | `model` | split on the first `/` into `execution.providerID` / `execution.modelID` (required) |
@@ -97,7 +97,9 @@ project write lock on every `syncProject` when the project path is known:
   file remains authoritative: the next reconciliation re-applies the file's
   definition (including `enabled`). Use `enabled: false` in the file to
   disable. Deleting a loop-sourced task through the API is rejected with a 400 —
-  the loop file is the removal surface.
+  the loop file is the removal surface. The scheduled-tasks UI marks loop tasks
+  as file-managed and disables their edit/enable/delete actions for the same
+  reason; `run now` remains available.
 
 ## Public exports (runtime.js)
 
diff --git a/packages/web/server/lib/scheduled-tasks/loops.js b/packages/web/server/lib/scheduled-tasks/loops.js
index 1fd71be7..7d15e671 100644
--- a/packages/web/server/lib/scheduled-tasks/loops.js
+++ b/packages/web/server/lib/scheduled-tasks/loops.js
@@ -41,6 +41,7 @@ import fs from 'fs';
 import os from 'os';
 import path from 'path';
 import { parseMdFile, getAncestors, findWorktreeRoot } from '../opencode/shared.js';
+import { MAX_TASK_NAME_LENGTH } from '../projects/project-config.js';
 
 const LOOP_DIR_NAME = 'loops';
 const USER_LOOP_ROOT = () => path.join(os.homedir(), '.agents', LOOP_DIR_NAME);
@@ -94,6 +95,12 @@ export const parseLoopDefinition = (filePath) => {
     console.warn(`[loops] skipped ${filePath}: frontmatter "name" is required`);
     return null;
   }
+  if (name.length > MAX_TASK_NAME_LENGTH) {
+    // Reject instead of clamping: task names are clamped to this length at
+    // storage time, so identity keys must match the stored value exactly.
+    console.warn(`[loops] skipped ${filePath}: frontmatter "name" exceeds ${MAX_TASK_NAME_LENGTH} characters`);
+    return null;
+  }
 
   const cron = asNonEmptyString(frontmatter.schedule);
   if (!cron) {
diff --git a/packages/web/server/lib/scheduled-tasks/loops.test.js b/packages/web/server/lib/scheduled-tasks/loops.test.js
index 7281adda..e05ef980 100644
--- a/packages/web/server/lib/scheduled-tasks/loops.test.js
+++ b/packages/web/server/lib/scheduled-tasks/loops.test.js
@@ -181,6 +181,33 @@ model: openai/gpt-5
       await cleanup();
     }
   });
+
+  it('rejects names longer than the storage limit', async () => {
+    const { projectPath, cleanup } = await createProject();
+    try {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+      try {
+        const filePath = path.join(projectPath, 'long-name.md');
+        await writeFile(filePath, `---
+name: ${'x'.repeat(81)}
+schedule: "0 9 * * *"
+model: openai/gpt-5
+---
+Run.
+`, 'utf8');
+
+        // Task names are clamped to 80 chars at storage time; a raw name that
+        // exceeds it could never match the stored task, so the file is treated
+        // as malformed rather than creating an unreachable definition.
+        expect(parseLoopDefinition(filePath)).toBeNull();
+        expect(warn).toHaveBeenCalled();
+      } finally {
+        warn.mockRestore();
+      }
+    } finally {
+      await cleanup();
+    }
+  });
 });
 
 describe('discoverLoops', () => {

From 9b6b90504ceb3e9a5d9f3bd596be78c3551f37fc Mon Sep 17 00:00:00 2001
From: makeittech <serkraser@gmail.com>
Date: Thu, 6 Aug 2026 09:49:31 +0300
Subject: [PATCH 34/57] fix(tasks): cover syncProject wiring and allow deleting
 orphans after file removal
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review follow-up:

- runtime.test.js: add syncProject wiring tests with a real temp-dir
  project and real project-config runtime — asserts reconcileLoopTasks is
  driven with the discovered loops when the project path is known (task
  created, nextRunAt computed) and that plain listing is used when the
  path cannot be resolved (reconcile not called).
- service.js: DELETE on a loop-owned task is rejected with a 400 only
  while its loop file still exists on disk; once the file is gone the
  orphan task can be deleted directly instead of waiting for the next
  reconcile. Tests use real temp files for both branches.
- DOCUMENTATION.md: delete semantics updated accordingly.
- PR description refreshed for the final HEAD (test counts, reconciliation
  contract, evidence wording).
---
 .../lib/scheduled-tasks/DOCUMENTATION.md      |   9 +-
 .../lib/scheduled-tasks/runtime.test.js       | 101 +++++++++++++++++-
 .../web/server/lib/scheduled-tasks/service.js |   9 +-
 .../lib/scheduled-tasks/service.test.js       |  58 +++++++---
 4 files changed, 156 insertions(+), 21 deletions(-)

diff --git a/packages/web/server/lib/scheduled-tasks/DOCUMENTATION.md b/packages/web/server/lib/scheduled-tasks/DOCUMENTATION.md
index 4de46ab5..4be03824 100644
--- a/packages/web/server/lib/scheduled-tasks/DOCUMENTATION.md
+++ b/packages/web/server/lib/scheduled-tasks/DOCUMENTATION.md
@@ -96,10 +96,11 @@ project write lock on every `syncProject` when the project path is known:
 - **UI edits** to a loop-sourced task are preserved in the config but the loop
   file remains authoritative: the next reconciliation re-applies the file's
   definition (including `enabled`). Use `enabled: false` in the file to
-  disable. Deleting a loop-sourced task through the API is rejected with a 400 —
-  the loop file is the removal surface. The scheduled-tasks UI marks loop tasks
-  as file-managed and disables their edit/enable/delete actions for the same
-  reason; `run now` remains available.
+  disable. Deleting a loop-sourced task through the API is rejected with a 400
+  while its loop file still exists on disk — the loop file is the removal
+  surface; once the file is gone, deleting the orphan task is allowed. The
+  scheduled-tasks UI marks loop tasks as file-managed and disables their
+  edit/enable/delete actions for the same reason; `run now` remains available.
 
 ## Public exports (runtime.js)
 
diff --git a/packages/web/server/lib/scheduled-tasks/runtime.test.js b/packages/web/server/lib/scheduled-tasks/runtime.test.js
index 7dafaca9..3a59b19f 100644
--- a/packages/web/server/lib/scheduled-tasks/runtime.test.js
+++ b/packages/web/server/lib/scheduled-tasks/runtime.test.js
@@ -1,5 +1,15 @@
-import { describe, expect, it } from 'vitest';
-import { computeNextRunAt, expandCommandGoalObjective, formatScheduledSessionTitle, parseScheduledCommandPrompt } from './runtime.js';
+import { describe, expect, it, vi } from 'vitest';
+import os from 'os';
+import path from 'path';
+import { mkdtemp, rm, mkdir, writeFile } from 'fs/promises';
+import {
+  computeNextRunAt,
+  expandCommandGoalObjective,
+  formatScheduledSessionTitle,
+  parseScheduledCommandPrompt,
+  createScheduledTasksRuntime,
+} from './runtime.js';
+import { createProjectConfigRuntime } from '../projects/project-config.js';
 
 describe('scheduled-tasks runtime helpers', () => {
   it('computes next daily run in timezone', () => {
@@ -109,3 +119,90 @@ describe('scheduled-tasks runtime helpers', () => {
       .toBe('Review the requested scope.\n\nauth module');
   });
 });
+
+describe('scheduled-tasks runtime syncProject wiring', () => {
+  const createTempProject = async () => {
+    const tempRoot = await mkdtemp(path.join(os.tmpdir(), 'oc-runtime-loop-'));
+    const repoPath = path.join(tempRoot, 'repo');
+    await mkdir(path.join(repoPath, '.agents', 'loops'), { recursive: true });
+    return {
+      tempRoot,
+      repoPath,
+      cleanup: async () => {
+        await rm(tempRoot, { recursive: true, force: true });
+      },
+    };
+  };
+
+  const createProjectConfig = async (tempRoot) => createProjectConfigRuntime({
+    fsPromises: await import('fs/promises'),
+    path,
+    projectsDirPath: path.join(tempRoot, 'config'),
+    createTaskID: () => 'task-fixed-id',
+  });
+
+  const createRuntimeDeps = (overrides = {}) => ({
+    buildOpenCodeUrl: () => 'http://localhost',
+    getOpenCodeAuthHeaders: () => ({}),
+    waitForOpenCodeReady: async () => {},
+    ...overrides,
+  });
+
+  it('reconciles discovered loops when the project path is known', async () => {
+    const { tempRoot, repoPath, cleanup } = await createTempProject();
+    try {
+      await writeFile(path.join(repoPath, '.agents', 'loops', 'daily.md'), `---
+name: daily
+schedule: "0 9 * * *"
+enabled: true
+model: openai/gpt-5
+---
+Run daily.
+`, 'utf8');
+
+      const projectConfigRuntime = await createProjectConfig(tempRoot);
+      const runtime = createScheduledTasksRuntime({
+        ...createRuntimeDeps(),
+        projectConfigRuntime,
+        listProjects: async () => [{ id: 'proj', path: repoPath }],
+      });
+
+      await runtime.syncProject('proj');
+
+      const tasks = await projectConfigRuntime.listScheduledTasks('proj');
+      expect(tasks).toHaveLength(1);
+      expect(tasks[0].id).toBe('loop:project:daily');
+      expect(tasks[0].loopFile).toBe(path.join(repoPath, '.agents', 'loops', 'daily.md'));
+      // syncTaskSchedule computed and persisted the next run for the enabled task.
+      expect(tasks[0].state.nextRunAt).toBeGreaterThan(0);
+    } finally {
+      await cleanup();
+    }
+  });
+
+  it('falls back to plain listing when the project path cannot be resolved', async () => {
+    const { tempRoot, cleanup } = await createTempProject();
+    try {
+      const projectConfigRuntime = await createProjectConfig(tempRoot);
+      const reconcileSpy = vi.spyOn(projectConfigRuntime, 'reconcileLoopTasks');
+      const listSpy = vi.spyOn(projectConfigRuntime, 'listScheduledTasks');
+
+      const runtime = createScheduledTasksRuntime({
+        ...createRuntimeDeps(),
+        projectConfigRuntime,
+        // Project not registered -> ensureProjectPath cannot resolve a path.
+        listProjects: async () => [],
+      });
+
+      await runtime.syncProject('proj');
+
+      expect(reconcileSpy).not.toHaveBeenCalled();
+      expect(listSpy).toHaveBeenCalledWith('proj');
+      expect(await projectConfigRuntime.listScheduledTasks('proj')).toEqual([]);
+      reconcileSpy.mockRestore();
+      listSpy.mockRestore();
+    } finally {
+      await cleanup();
+    }
+  });
+});
diff --git a/packages/web/server/lib/scheduled-tasks/service.js b/packages/web/server/lib/scheduled-tasks/service.js
index 33d69f7d..4d94251a 100644
--- a/packages/web/server/lib/scheduled-tasks/service.js
+++ b/packages/web/server/lib/scheduled-tasks/service.js
@@ -1,3 +1,4 @@
+import fs from 'node:fs';
 import path from 'node:path';
 import { OpenChamberControlError } from '../openchamber-control/error.js';
 
@@ -80,10 +81,12 @@ export const createScheduledTaskService = (dependencies) => {
     if (!normalizedTaskID) throw new OpenChamberControlError('taskId is required', 400);
     const current = await projectConfigRuntime.listScheduledTasks(projectID);
     const existing = current.find((task) => task.id === normalizedTaskID) || null;
-    if (existing?.loopFile) {
+    if (existing?.loopFile && fs.existsSync(existing.loopFile)) {
       // Loop tasks are owned by their `.agents/loops` markdown file: deleting
-      // the JSON row would be silently undone by the next reconcile. The file
-      // itself is the removal surface.
+      // the JSON row would be silently undone by the next reconcile while the
+      // file exists. The file itself is the removal surface. Once the file is
+      // gone (the task is an orphan that the next sync would remove anyway),
+      // deleting the row is safe and allowed.
       throw new OpenChamberControlError(
         'Loop task is managed by its .agents/loops markdown file; delete the file to remove the task',
         400,
diff --git a/packages/web/server/lib/scheduled-tasks/service.test.js b/packages/web/server/lib/scheduled-tasks/service.test.js
index 07d6bf70..a90c1b64 100644
--- a/packages/web/server/lib/scheduled-tasks/service.test.js
+++ b/packages/web/server/lib/scheduled-tasks/service.test.js
@@ -1,4 +1,7 @@
 import { describe, expect, it, vi } from 'vitest';
+import os from 'os';
+import path from 'path';
+import { mkdtemp, rm, writeFile } from 'fs/promises';
 import { createScheduledTaskService } from './service.js';
 
 const createService = (overrides = {}) => {
@@ -32,19 +35,50 @@ const loopTask = {
 };
 
 describe('scheduled-task service remove', () => {
-  it('rejects deleting a loop-sourced task without touching storage', async () => {
-    const { service, projectConfigRuntime, scheduledTasksRuntime } = createService({
-      projectConfigRuntime: {
-        listScheduledTasks: vi.fn(async () => [loopTask]),
-      },
-    });
+  it('rejects deleting a loop-sourced task while its loop file still exists', async () => {
+    const tempRoot = await mkdtemp(path.join(os.tmpdir(), 'oc-loop-delete-'));
+    try {
+      const loopFilePath = path.join(tempRoot, 'daily.md');
+      await writeFile(loopFilePath, '---\nname: daily-digest\n---\nRun.\n', 'utf8');
 
-    await expect(service.remove('project-test', loopTask.id)).rejects.toMatchObject({
-      statusCode: 400,
-      message: expect.stringContaining('delete the file to remove the task'),
-    });
-    expect(projectConfigRuntime.deleteScheduledTask).not.toHaveBeenCalled();
-    expect(scheduledTasksRuntime.syncProject).not.toHaveBeenCalled();
+      const { service, projectConfigRuntime, scheduledTasksRuntime } = createService({
+        projectConfigRuntime: {
+          listScheduledTasks: vi.fn(async () => [{ ...loopTask, loopFile: loopFilePath }]),
+        },
+      });
+
+      await expect(service.remove('project-test', loopTask.id)).rejects.toMatchObject({
+        statusCode: 400,
+        message: expect.stringContaining('delete the file to remove the task'),
+      });
+      expect(projectConfigRuntime.deleteScheduledTask).not.toHaveBeenCalled();
+      expect(scheduledTasksRuntime.syncProject).not.toHaveBeenCalled();
+    } finally {
+      await rm(tempRoot, { recursive: true, force: true });
+    }
+  });
+
+  it('allows deleting a loop-sourced task once its loop file is gone', async () => {
+    const tempRoot = await mkdtemp(path.join(os.tmpdir(), 'oc-loop-delete-'));
+    try {
+      // The loop file was removed from disk; the orphan task is allowed to be
+      // deleted directly instead of waiting for the next reconcile.
+      const loopFilePath = path.join(tempRoot, 'gone.md');
+
+      const { service, projectConfigRuntime, scheduledTasksRuntime } = createService({
+        projectConfigRuntime: {
+          listScheduledTasks: vi.fn(async () => [{ ...loopTask, loopFile: loopFilePath }]),
+        },
+      });
+
+      const tasks = await service.remove('project-test', loopTask.id);
+
+      expect(projectConfigRuntime.deleteScheduledTask).toHaveBeenCalledWith('project-test', loopTask.id);
+      expect(scheduledTasksRuntime.syncProject).toHaveBeenCalled();
+      expect(Array.isArray(tasks)).toBe(true);
+    } finally {
+      await rm(tempRoot, { recursive: true, force: true });
+    }
   });
 
   it('deletes JSON-configured tasks normally', async () => {

From 0a4fd7c5fb93a2e082555956e0f535d252abfd47 Mon Sep 17 00:00:00 2001
From: makeittech <serkraser@gmail.com>
Date: Thu, 6 Aug 2026 09:56:11 +0300
Subject: [PATCH 35/57] docs(tasks): add loops quick-start to the
 scheduled-tasks page

User-facing onboarding for markdown loop tasks: where .agents/loops
files live (project + user scope), a copy-paste sample file, the
frontmatter field table, and the behavior contract (file authoritative,
off by default, rename/malformed semantics, run-now still available).
Also lists the cron schedule type in the UI task creation steps, which
the page previously omitted.
---
 .../docs/content/docs/scheduled-tasks.mdx     | 43 +++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/packages/docs/content/docs/scheduled-tasks.mdx b/packages/docs/content/docs/scheduled-tasks.mdx
index e7753190..4f5a6554 100644
--- a/packages/docs/content/docs/scheduled-tasks.mdx
+++ b/packages/docs/content/docs/scheduled-tasks.mdx
@@ -15,6 +15,7 @@ A scheduled task runs a prompt for you on a schedule — for example, a daily "s
    - **daily** — at one or more times each day
    - **weekly** — on chosen weekdays and times
    - **once** — a single date and time
+   - **cron** — an arbitrary cron expression
 4. Set what it does: the prompt to send, and the provider, model, and agent to use. The prompt can be a slash command, like `/review`.
 5. Save, and make sure the task is enabled.
 
@@ -22,6 +23,48 @@ You can run any task immediately with **run now** to check it does what you expe
 
 Check **Run as goal** to make the run pursue its prompt to completion instead of stopping after one reply — see [Session Goals](/session-goals/).
 
+## Loops: scheduled tasks as markdown files
+
+A **loop** is a scheduled task defined as a portable markdown file you can commit to your repo. Drop a file into `.agents/loops/` and the task appears on the next sync — no dialog needed:
+
+```markdown
+---
+name: daily-digest
+schedule: "0 9 * * *"
+enabled: true
+model: anthropic/claude-sonnet-4-5
+agent: plan
+timezone: Europe/Kyiv
+---
+Summarize repository changes since yesterday and post the digest.
+```
+
+### Where files live
+
+- **Project scope** — `.agents/loops/*.md` in the project directory or any ancestor directory up to the git worktree root.
+- **User scope** — `~/.agents/loops/*.md` applies to every project you open.
+
+If a project loop and a user loop share a name, the project loop wins.
+
+### Fields
+
+| Field | Meaning |
+|---|---|
+| `name` | Task name (required, max 80 characters). |
+| `schedule` | Cron expression (required) — loop files are cron-only. |
+| `enabled` | Set `true` to run. Loops are **off by default**, so committing a file never starts running a task on its own. |
+| `model` | `provider/model` (required), e.g. `anthropic/claude-sonnet-4-5`. |
+| `agent` | Agent to use (optional). |
+| `timezone` | IANA timezone (optional, defaults to the server zone). |
+| body | The execution prompt (required). Can be a slash command, like `/review src/`. |
+
+### How loops behave
+
+- The **file is authoritative** while it exists: edits made in the UI are reverted on the next sync. The scheduled-tasks dialog marks loop tasks and disables their edit/enable/delete actions — **run now** still works. To stop a loop, delete the file (or set `enabled: false`).
+- Runtime state (last run, next run, status) lives in the project config and is never written back into the markdown file.
+- Renaming the `name` field renames the task in place. If a loop file temporarily fails to parse (mid-edit, merge conflict), its task is kept with the last good definition until the file is fixed.
+- `daily`/`weekly`/`once` schedules and goal settings remain UI-only; loop files are always cron.
+
 ## What success looks like
 
 After a run, the task shows when it last ran, whether it succeeded, and a link to the session it created. If a run fails, the error is shown there too.

From 7d9af7aa3abf6e857006c9eaa26bcedd6a6b272f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pascal=20Andr=C3=A9?= <pascalandr@gmail.com>
Date: Thu, 6 Aug 2026 19:58:49 +0200
Subject: [PATCH 36/57] fix(chat): expand shell output by default (#2492)

---
 packages/ui/src/components/chat/message/MessageBody.tsx | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/packages/ui/src/components/chat/message/MessageBody.tsx b/packages/ui/src/components/chat/message/MessageBody.tsx
index ae701111..d2e04411 100644
--- a/packages/ui/src/components/chat/message/MessageBody.tsx
+++ b/packages/ui/src/components/chat/message/MessageBody.tsx
@@ -284,16 +284,15 @@ const UserSubtaskPart: React.FC<{ part: SubtaskPartLike }> = ({ part }) => {
 const SHELL_CODE_TAG_STYLE: React.CSSProperties = { background: 'transparent', backgroundColor: 'transparent' };
 
 const UserShellActionPart: React.FC<{ part: ShellActionPartLike }> = ({ part }) => {
-    const [expanded, setExpanded] = React.useState(false);
+    const output = typeof part.shellAction?.output === 'string' ? part.shellAction.output : '';
+    const [expanded, setExpanded] = React.useState(true);
     const [copiedOutput, setCopiedOutput] = React.useState(false);
     const copiedResetTimeoutRef = React.useRef<number | null>(null);
     const { t } = useI18n();
 
     const command = typeof part.shellAction?.command === 'string' ? part.shellAction.command.trim() : '';
-    const output = typeof part.shellAction?.output === 'string' ? part.shellAction.output : '';
     const status = typeof part.shellAction?.status === 'string' ? part.shellAction.status.trim().toLowerCase() : '';
     const hasOutput = output.trim().length > 0;
-
     const clearCopiedResetTimeout = React.useCallback(() => {
         if (copiedResetTimeoutRef.current !== null && typeof window !== 'undefined') {
             window.clearTimeout(copiedResetTimeoutRef.current);

From 3f5a453d31e4fa11a932fd4dc1afe2f8b7330ed6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pascal=20Andr=C3=A9?= <pascalandr@gmail.com>
Date: Thu, 6 Aug 2026 20:06:54 +0200
Subject: [PATCH 37/57] fix(desktop): preserve native taskbar minimize (#2494)

---
 packages/electron/main.mjs | 13 ++++++-------
 1 file changed, 6 insertions(+), 7 deletions(-)

diff --git a/packages/electron/main.mjs b/packages/electron/main.mjs
index e9bca981..8be0f076 100644
--- a/packages/electron/main.mjs
+++ b/packages/electron/main.mjs
@@ -2463,12 +2463,6 @@ const createBrowserWindow = ({ label, restoreGeometry, url, runtimeConfig = {} }
   browserWindow.on('move', () => {
     debounceWindowStatePersist(browserWindow, false);
   });
-  browserWindow.on('minimize', (event) => {
-    if (!shouldHideMainWindowToTray(browserWindow)) return;
-    debounceWindowStatePersist(browserWindow, true);
-    event.preventDefault();
-    browserWindow.hide();
-  });
   browserWindow.on('close', (event) => {
     if (!state.quitRequested && shouldHideMainWindowToTray(browserWindow)) {
       debounceWindowStatePersist(browserWindow, true);
@@ -4448,7 +4442,12 @@ const handleInvoke = async (browserWindow, command, args = {}) => {
 
     case 'desktop_minimize_current_window':
       if (browserWindow && !browserWindow.isDestroyed()) {
-        browserWindow.minimize();
+        if (shouldHideMainWindowToTray(browserWindow)) {
+          debounceWindowStatePersist(browserWindow, true);
+          browserWindow.hide();
+        } else {
+          browserWindow.minimize();
+        }
       }
       return null;
 

From fa63866cbb813c26af8a452500b7d777209e4679 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=A9rgio=20Pedro?= <giofsp1@gmail.com>
Date: Thu, 6 Aug 2026 19:10:22 +0100
Subject: [PATCH 38/57] fix(ui): make overlay scrollbar persistent on desktop
 shells (#2581)

PR #2520 fixed #2475 in the wrong layer (overflow classes on
SettingsView.tsx wrapper divs that aren't the actual scroll containers),
so the "no scrollbar in Settings" bug shipped in v1.17.2 unchanged, and
the sessions feed has the same underlying issue (#2402).

The actual scroll containers render through ScrollableOverlay ->
OverlayScrollbar, which hides the native scrollbar and draws its own
JS thumb that auto-hides ~1s after scroll activity stops, with a
second CSS rule fully hiding that thumb inside Settings specifically.

Fix both at the shared component/CSS layer so every consumer (Settings,
sessions feed, git panels, chat, etc.) gets a persistent scrollbar on
desktop shells (Electron + VS Code webview) in one change:

- OverlayScrollbar.tsx: skip the auto-hide timer and show the thumb
  immediately on mount when content overflows, on desktop runtimes.
  userIntentOnly consumers (chat auto-follow scroll, reasoning blocks)
  keep today's intent-gated behavior unchanged.
- index.css: scope the Settings-specific hide rule to non-desktop, so
  mobile/web keep existing behavior and desktop gets the thumb back.
---
 .../ui/src/components/ui/OverlayScrollbar.tsx | 20 +++++++++++++++++--
 packages/ui/src/index.css                     |  6 ++++--
 2 files changed, 22 insertions(+), 4 deletions(-)

diff --git a/packages/ui/src/components/ui/OverlayScrollbar.tsx b/packages/ui/src/components/ui/OverlayScrollbar.tsx
index d1026abb..7a409d00 100644
--- a/packages/ui/src/components/ui/OverlayScrollbar.tsx
+++ b/packages/ui/src/components/ui/OverlayScrollbar.tsx
@@ -25,6 +25,12 @@ const isSameThumbMetrics = (a: ThumbMetrics, b: ThumbMetrics): boolean => {
   return Math.abs(a.length - b.length) < METRIC_EPSILON && Math.abs(a.offset - b.offset) < METRIC_EPSILON;
 };
 
+// Desktop shells (Electron, VS Code webview) use persistent, not
+// auto-hiding, scrollbars. Reads the same `desktop-runtime` root class that
+// index.css keys off, so JS and CSS never disagree on what counts as desktop.
+const isDesktopScrollbarRuntime = (): boolean =>
+  typeof document !== "undefined" && document.documentElement.classList.contains("desktop-runtime");
+
 const OverlayScrollbarComponent: React.FC<OverlayScrollbarProps> = ({
   containerRef,
   minThumbSize = 32,
@@ -128,8 +134,15 @@ const OverlayScrollbarComponent: React.FC<OverlayScrollbarProps> = ({
     if (isHoveringRef.current) {
       return;
     }
+    // Desktop shells keep the thumb visible once shown instead of
+    // auto-hiding it after a delay. userIntentOnly callers (e.g. chat
+    // auto-follow scroll) opt out of persistence on purpose, so they keep
+    // the existing auto-hide behavior even on desktop.
+    if (isDesktopScrollbarRuntime() && !userIntentOnly) {
+      return;
+    }
     hideTimeoutRef.current = setTimeout(() => setVisible(false), hideDelayMs);
-  }, [hideDelayMs]);
+  }, [hideDelayMs, userIntentOnly]);
 
   const markUserIntent = React.useCallback(() => {
     lastUserIntentAtRef.current = Date.now();
@@ -162,7 +175,10 @@ const OverlayScrollbarComponent: React.FC<OverlayScrollbarProps> = ({
     if (!container) return;
 
     updateMetrics();
-    setVisible(false);
+    // On desktop shells, show the thumb immediately if content overflows
+    // instead of waiting for the first scroll event (persistent affordance,
+    // matching native desktop scrollbar conventions).
+    setVisible(isDesktopScrollbarRuntime() && !userIntentOnly);
 
     const onScroll = () => handleScroll();
     const onKeyDown = (event: KeyboardEvent) => {
diff --git a/packages/ui/src/index.css b/packages/ui/src/index.css
index b6462769..4805a2c3 100644
--- a/packages/ui/src/index.css
+++ b/packages/ui/src/index.css
@@ -1804,8 +1804,10 @@ input[aria-label="Terminal input"] {
 
 }
 
-/* Settings dialog: hide the overlay scrollbar; wheel/keyboard scroll still works. */
-[data-settings-view="true"] .overlay-scrollbar {
+/* Settings dialog: hide the overlay scrollbar on mobile/web; wheel/keyboard
+   scroll still works. Desktop shells keep the persistent scrollbar so the
+   Settings sub-panels aren't left with no scroll affordance at all. */
+html:not(.desktop-runtime) [data-settings-view="true"] .overlay-scrollbar {
   display: none;
 }
 

From bcc64f7586f500ae3e028398c14dbec02d99a1b1 Mon Sep 17 00:00:00 2001
From: Aman Tahiliani <65684756+AmanTahiliani@users.noreply.github.com>
Date: Thu, 6 Aug 2026 14:17:16 -0400
Subject: [PATCH 39/57] fix(settings): preserve notification template edits
 (#2300)

---
 .../openchamber/NotificationSettings.tsx      |  8 ++---
 .../useUIStore.notificationTemplates.test.ts  | 29 +++++++++++++++++++
 packages/ui/src/stores/useUIStore.ts          | 12 ++++++--
 3 files changed, 43 insertions(+), 6 deletions(-)
 create mode 100644 packages/ui/src/stores/useUIStore.notificationTemplates.test.ts

diff --git a/packages/ui/src/components/sections/openchamber/NotificationSettings.tsx b/packages/ui/src/components/sections/openchamber/NotificationSettings.tsx
index e0cb8d44..0914e02a 100644
--- a/packages/ui/src/components/sections/openchamber/NotificationSettings.tsx
+++ b/packages/ui/src/components/sections/openchamber/NotificationSettings.tsx
@@ -152,13 +152,13 @@ export const NotificationSettings: React.FC = () => {
     field: 'title' | 'message',
     value: string,
   ) => {
-    setNotificationTemplates({
-      ...notificationTemplates,
+    setNotificationTemplates((current) => ({
+      ...current,
       [event]: {
-        ...notificationTemplates[event],
+        ...current[event],
         [field]: value,
       },
-    });
+    }));
   };
 
   const base64UrlToUint8Array = (base64Url: string): Uint8Array<ArrayBuffer> => {
diff --git a/packages/ui/src/stores/useUIStore.notificationTemplates.test.ts b/packages/ui/src/stores/useUIStore.notificationTemplates.test.ts
new file mode 100644
index 00000000..de4eef7e
--- /dev/null
+++ b/packages/ui/src/stores/useUIStore.notificationTemplates.test.ts
@@ -0,0 +1,29 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { useUIStore } from './useUIStore';
+
+const initialTemplates = useUIStore.getState().notificationTemplates;
+
+afterEach(() => {
+  useUIStore.setState({ notificationTemplates: initialTemplates });
+});
+
+describe('useUIStore notification templates', () => {
+  test('preserves rapid updates to separate template fields', () => {
+    const { setNotificationTemplates } = useUIStore.getState();
+
+    setNotificationTemplates((current) => ({
+      ...current,
+      completion: { ...current.completion, title: 'Completed' },
+    }));
+    setNotificationTemplates((current) => ({
+      ...current,
+      error: { ...current.error, message: 'Failed' },
+    }));
+
+    expect(useUIStore.getState().notificationTemplates).toEqual({
+      ...initialTemplates,
+      completion: { ...initialTemplates.completion, title: 'Completed' },
+      error: { ...initialTemplates.error, message: 'Failed' },
+    });
+  });
+});
diff --git a/packages/ui/src/stores/useUIStore.ts b/packages/ui/src/stores/useUIStore.ts
index d00bb6ff..0849cfdc 100644
--- a/packages/ui/src/stores/useUIStore.ts
+++ b/packages/ui/src/stores/useUIStore.ts
@@ -842,7 +842,9 @@ interface UIStore {
   setNotifyOnCompletion: (value: boolean) => void;
   setNotifyOnError: (value: boolean) => void;
   setNotifyOnQuestion: (value: boolean) => void;
-  setNotificationTemplates: (templates: UIStore['notificationTemplates']) => void;
+  setNotificationTemplates: (
+    templates: UIStore['notificationTemplates'] | ((current: UIStore['notificationTemplates']) => UIStore['notificationTemplates']),
+  ) => void;
   setSummarizeLastMessage: (value: boolean) => void;
   setSummaryThreshold: (value: number) => void;
   setSummaryLength: (value: number) => void;
@@ -2135,7 +2137,13 @@ export const useUIStore = create<UIStore>()(
         setNotifyOnCompletion: (value) => { set({ notifyOnCompletion: value }); },
         setNotifyOnError: (value) => { set({ notifyOnError: value }); },
         setNotifyOnQuestion: (value) => { set({ notifyOnQuestion: value }); },
-        setNotificationTemplates: (templates) => { set({ notificationTemplates: templates }); },
+        setNotificationTemplates: (templates) => {
+          set((state) => ({
+            notificationTemplates: typeof templates === 'function'
+              ? templates(state.notificationTemplates)
+              : templates,
+          }));
+        },
         setSummarizeLastMessage: (value) => { set({ summarizeLastMessage: value }); },
         setSummaryThreshold: (value) => { set({ summaryThreshold: value }); },
         setSummaryLength: (value) => { set({ summaryLength: value }); },

From 4bb89bf6a6ac0b80c8376f8f2167fbc14012fabc Mon Sep 17 00:00:00 2001
From: TPOB <19909103+TTTPOB@users.noreply.github.com>
Date: Fri, 7 Aug 2026 02:37:41 +0800
Subject: [PATCH 40/57] fix(vscode): open notebook links in notebook editor
 (#2373)

---
 .../vscode/src/bridge-system-runtime.test.js  | 98 +++++++++++++++++++
 packages/vscode/src/bridge-system-runtime.ts  |  3 +-
 2 files changed, 99 insertions(+), 2 deletions(-)
 create mode 100644 packages/vscode/src/bridge-system-runtime.test.js

diff --git a/packages/vscode/src/bridge-system-runtime.test.js b/packages/vscode/src/bridge-system-runtime.test.js
new file mode 100644
index 00000000..09a17d26
--- /dev/null
+++ b/packages/vscode/src/bridge-system-runtime.test.js
@@ -0,0 +1,98 @@
+import { beforeEach, describe, expect, mock, test } from 'bun:test';
+
+const executeCommand = mock(async () => undefined);
+
+class Position {
+  constructor(line, character) {
+    this.line = line;
+    this.character = character;
+  }
+}
+
+class Range {
+  constructor(start, end) {
+    this.start = start;
+    this.end = end;
+  }
+}
+
+mock.module('vscode', () => ({
+  commands: { executeCommand },
+  workspace: {
+    workspaceFolders: [],
+  },
+  Uri: {
+    file: (fsPath) => ({ scheme: 'file', fsPath }),
+  },
+  Position,
+  Range,
+}));
+
+mock.module('./opencodeConfig', () => ({
+  removeProviderConfig: mock(),
+  getProviderSources: mock(),
+}));
+mock.module('./opencodeAuth', () => ({
+  getProviderAuth: mock(),
+  removeProviderAuth: mock(),
+}));
+mock.module('./quotaProviders', () => ({
+  fetchQuotaForProvider: mock(),
+  listConfiguredQuotaProviders: mock(),
+}));
+mock.module('./opencodeGoQuota', () => ({ fetchOpenCodeGoUsage: mock() }));
+mock.module('./quotaCredentials', () => ({
+  credentialStatus: mock(),
+  deleteCredential: mock(),
+  importCursorCredential: mock(),
+  normalizeCredential: mock(),
+  readCredential: mock(),
+  validateCredential: mock(),
+  writeCredential: mock(),
+}));
+mock.module('./sessionActivityWatcher', () => ({ getSessionActivitySnapshot: mock() }));
+
+const { handleSystemBridgeMessage } = await import('./bridge-system-runtime.ts');
+
+const deps = {
+  resolveUserPath: (value) => value,
+  fetchModelsMetadata: async () => ({}),
+  updateCheckUrl: 'https://example.com/update-check',
+  clientReloadDelayMs: 800,
+};
+
+describe('VS Code system bridge editor:openFile', () => {
+  beforeEach(() => {
+    executeCommand.mockClear();
+  });
+
+  test('uses vscode.open so VS Code can select the notebook editor', async () => {
+    const response = await handleSystemBridgeMessage({
+      id: 'open-notebook',
+      type: 'editor:openFile',
+      payload: { path: '/workspace/notebook.ipynb' },
+    }, undefined, deps);
+
+    expect(response).toEqual({ id: 'open-notebook', type: 'editor:openFile', success: true });
+    expect(executeCommand).toHaveBeenCalledWith(
+      'vscode.open',
+      { scheme: 'file', fsPath: '/workspace/notebook.ipynb' },
+      {},
+    );
+  });
+
+  test('preserves line and column selection for regular files', async () => {
+    await handleSystemBridgeMessage({
+      id: 'open-text',
+      type: 'editor:openFile',
+      payload: { path: '/workspace/source.ts', line: 4, column: 7 },
+    }, undefined, deps);
+
+    const position = new Position(3, 7);
+    expect(executeCommand).toHaveBeenCalledWith(
+      'vscode.open',
+      { scheme: 'file', fsPath: '/workspace/source.ts' },
+      { selection: new Range(position, position) },
+    );
+  });
+});
diff --git a/packages/vscode/src/bridge-system-runtime.ts b/packages/vscode/src/bridge-system-runtime.ts
index 67ec64e1..5564bc23 100644
--- a/packages/vscode/src/bridge-system-runtime.ts
+++ b/packages/vscode/src/bridge-system-runtime.ts
@@ -356,13 +356,12 @@ export async function handleSystemBridgeMessage(
     case 'editor:openFile': {
       const { path: filePath, line, column } = payload as { path: string; line?: number; column?: number };
       try {
-        const doc = await vscode.workspace.openTextDocument(filePath);
         const options: vscode.TextDocumentShowOptions = {};
         if (typeof line === 'number') {
           const pos = new vscode.Position(Math.max(0, line - 1), column || 0);
           options.selection = new vscode.Range(pos, pos);
         }
-        await vscode.window.showTextDocument(doc, options);
+        await vscode.commands.executeCommand('vscode.open', vscode.Uri.file(filePath), options);
         return { id, type, success: true };
       } catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);

From fe331c093b16e4efa825cc42cee8551e8ab15cf4 Mon Sep 17 00:00:00 2001
From: Serhii Dziupin <serkraser@gmail.com>
Date: Thu, 6 Aug 2026 22:19:50 +0300
Subject: [PATCH 41/57] fix(ui): never auto-send the message queue into a
 streaming turn (#2642)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The queue auto-send gate treated a missing session status entry as idle,
but the server's /session/status map only lists busy/retry sessions — a
missed busy event leaves no entry while a turn is still streaming. On a
client that missed the busy event (e.g. mobile reconnect window), queued
follow-ups were dispatched into the running turn; OpenCode then merged
both prompts into one model response instead of serializing them.

Extract resolveQueuedSessionStatusType and mirror useSessionActivity's
fallback: a trailing in-flight assistant message means the session is
still busy, so the queue waits for the real idle edge. Subscribe the
effect to messages so the queue drains as soon as the turn completes
even when status events were missed.
---
 .../hooks/useQueuedMessageAutoSend.test.ts    | 58 ++++++++++++++++++-
 .../ui/src/hooks/useQueuedMessageAutoSend.ts  | 45 +++++++++++++-
 2 files changed, 99 insertions(+), 4 deletions(-)

diff --git a/packages/ui/src/hooks/useQueuedMessageAutoSend.test.ts b/packages/ui/src/hooks/useQueuedMessageAutoSend.test.ts
index 70c5eb43..f5a6a343 100644
--- a/packages/ui/src/hooks/useQueuedMessageAutoSend.test.ts
+++ b/packages/ui/src/hooks/useQueuedMessageAutoSend.test.ts
@@ -1,6 +1,8 @@
 import { beforeEach, describe, expect, mock, test } from 'bun:test';
-import type { Agent } from '@opencode-ai/sdk/v2';
+import type { Agent, Message } from '@opencode-ai/sdk/v2';
 import type { QueuedMessage } from '../stores/messageQueueStore';
+import { ChildStoreManager } from '@/sync/child-store';
+import { setSyncRefs } from '@/sync/sync-refs';
 
 let visibleAgents: Agent[] = [];
 const sendMessageCalls: unknown[][] = [];
@@ -32,6 +34,7 @@ import {
   createQueuedAutoSendRetryScheduler,
   getQueuedAutoSendRetryDelayMs,
   isQueuedAutoSendBackedOff,
+  resolveQueuedSessionStatusType,
   sendQueuedAutoSendPayload,
   shouldDispatchQueuedAutoSend,
 } from './useQueuedMessageAutoSend';
@@ -119,6 +122,59 @@ describe('queued auto-send retry backoff', () => {
   });
 });
 
+describe('resolveQueuedSessionStatusType', () => {
+  const DIRECTORY = '/repo';
+
+  const assistantMessage = (id: string, completed?: number): Message => ({
+    id,
+    role: 'assistant',
+    sessionID: 'ses_1',
+    time: { created: 1, ...(completed !== undefined ? { completed } : {}) },
+  } as Message);
+
+  let childStores: ChildStoreManager;
+
+  beforeEach(() => {
+    childStores = new ChildStoreManager();
+    const store = childStores.ensureChild(DIRECTORY, { bootstrap: false });
+    store.setState({ status: 'complete', session_status: {}, message: {} });
+    setSyncRefs({} as never, childStores, DIRECTORY);
+  });
+
+  test('treats a session with an in-flight assistant turn as busy even when the status entry is missing', () => {
+    // The server status map only lists busy/retry sessions, so a missed busy
+    // event leaves NO status entry while the turn is still streaming. The
+    // queue gate must not read that absence as idle: queued prompts would be
+    // dispatched into the running turn and merged into one model response.
+    childStores.ensureChild(DIRECTORY, { bootstrap: false }).setState({
+      message: { ses_1: [assistantMessage('msg_streaming')] },
+    });
+
+    expect(resolveQueuedSessionStatusType('ses_1', DIRECTORY)).toBe('busy');
+  });
+
+  test('resolves an explicit busy or retry status entry', () => {
+    const store = childStores.ensureChild(DIRECTORY, { bootstrap: false });
+    store.setState({ session_status: { ses_1: { type: 'busy' } } });
+    expect(resolveQueuedSessionStatusType('ses_1', DIRECTORY)).toBe('busy');
+    store.setState({ session_status: { ses_1: { type: 'retry', attempt: 2, message: 'boom', next: 30 } } });
+    expect(resolveQueuedSessionStatusType('ses_1', DIRECTORY)).toBe('retry');
+  });
+
+  test('resolves idle when the trailing assistant message has completed', () => {
+    const store = childStores.ensureChild(DIRECTORY, { bootstrap: false });
+    store.setState({ message: { ses_1: [assistantMessage('msg_done', 5)] } });
+    expect(resolveQueuedSessionStatusType('ses_1', DIRECTORY)).toBe('idle');
+  });
+
+  test('resolves an explicit idle entry and unknown sessions as idle', () => {
+    const store = childStores.ensureChild(DIRECTORY, { bootstrap: false });
+    store.setState({ session_status: { ses_1: { type: 'idle' } } });
+    expect(resolveQueuedSessionStatusType('ses_1', DIRECTORY)).toBe('idle');
+    expect(resolveQueuedSessionStatusType('ses_unknown', DIRECTORY)).toBe('idle');
+  });
+});
+
 describe('buildQueuedAutoSendPayload', () => {
   beforeEach(() => {
     visibleAgents = [];
diff --git a/packages/ui/src/hooks/useQueuedMessageAutoSend.ts b/packages/ui/src/hooks/useQueuedMessageAutoSend.ts
index e7b39c97..38e95713 100644
--- a/packages/ui/src/hooks/useQueuedMessageAutoSend.ts
+++ b/packages/ui/src/hooks/useQueuedMessageAutoSend.ts
@@ -173,11 +173,50 @@ export const shouldDispatchQueuedAutoSend = (
     && currentStatusType === 'idle';
 };
 
+/**
+ * Resolve the live status the queue gate should honor for a session.
+ *
+ * The server's `/session/status` map only lists busy/retry sessions — idle
+ * sessions are absent — so a missing entry means "idle per the snapshot", not
+ * "no information". A missed busy event therefore leaves no entry while a turn
+ * is still streaming. The trailing in-flight assistant message is the live
+ * evidence of that running turn: treat it as busy so the queue never dispatches
+ * into it (mirrors `useSessionActivity`'s fallback). The entry becomes idle the
+ * moment the message completes or an idle status event lands. This reads the
+ * directory child store directly so both the effect-loop gate and the
+ * dispatch-time re-check agree.
+ */
+export const resolveQueuedSessionStatusType = (
+  sessionId: string,
+  directory: string,
+): SessionStatusType => {
+  const state = getDirectoryState(directory);
+  const statusType = state?.session_status?.[sessionId]?.type;
+  if (statusType === 'busy' || statusType === 'retry') {
+    return statusType;
+  }
+  const sessionMessages = state?.message?.[sessionId];
+  const lastMessage = sessionMessages && sessionMessages.length > 0
+    ? sessionMessages[sessionMessages.length - 1]
+    : undefined;
+  if (
+    lastMessage?.role === 'assistant'
+    && typeof (lastMessage as { time?: { completed?: number } }).time?.completed !== 'number'
+  ) {
+    return 'busy';
+  }
+  return 'idle';
+};
+
 export function useQueuedMessageAutoSend(enabledOrOptions?: boolean | { enabled?: boolean }) {
   const enabled = typeof enabledOrOptions === 'boolean' ? enabledOrOptions : (enabledOrOptions?.enabled ?? true);
   const queuedMessages = useMessageQueueStore((state) => state.queuedMessages);
   const autoReviewRuns = useAutoReviewStore((state) => state.runsByOriginalSessionID);
   const sessionStatusRecord = useDirectorySync((state) => state.session_status);
+  // Message completion clears the in-flight fallback in
+  // resolveQueuedSessionStatusType; subscribe so the queue drains the moment
+  // the trailing assistant message completes even if status events were missed.
+  const sessionMessages = useDirectorySync((state) => state.message);
   const currentDirectory = useDirectoryStore((state) => state.currentDirectory);
 
   const inFlightSessionsRef = React.useRef<Set<string>>(new Set());
@@ -216,7 +255,7 @@ export function useQueuedMessageAutoSend(enabledOrOptions?: boolean | { enabled?
         return;
       }
 
-      const currentStatus = getDirectoryState(target.directory)?.session_status?.[sessionId]?.type ?? 'idle';
+      const currentStatus = resolveQueuedSessionStatusType(sessionId, target.directory);
       if (currentStatus !== 'idle') {
         return;
       }
@@ -294,7 +333,7 @@ export function useQueuedMessageAutoSend(enabledOrOptions?: boolean | { enabled?
       const target = parseMessageQueueKey(key);
       if (!target || target.runtimeKey !== getRuntimeKey() || target.directory !== currentDirectory) return;
       const { sessionId } = target;
-      const currentStatusType = (statusRecord[sessionId]?.type ?? 'idle') as SessionStatusType;
+      const currentStatusType = resolveQueuedSessionStatusType(sessionId, target.directory);
       const previousStatusType = previousStatusRef.current.get(sessionId);
       const wasAutoReviewBlocked = autoReviewBlockedSessionsRef.current.has(sessionId);
       const isAutoReviewRunning = useAutoReviewStore.getState().isRunningForSession(sessionId);
@@ -315,5 +354,5 @@ export function useQueuedMessageAutoSend(enabledOrOptions?: boolean | { enabled?
     });
 
     previousStatusRef.current = nextStatusMap;
-  }, [enabled, queuedMessages, sessionStatusRecord, autoReviewRuns, currentDirectory, retryTick, retryScheduler]);
+  }, [enabled, queuedMessages, sessionStatusRecord, sessionMessages, autoReviewRuns, currentDirectory, retryTick, retryScheduler]);
 }

From 2c331e2f8b861347f50d2085043c8d1b71de589c Mon Sep 17 00:00:00 2001
From: Chiam <77107215+chiamsun@users.noreply.github.com>
Date: Fri, 7 Aug 2026 03:38:34 +0800
Subject: [PATCH 42/57] fix(ui): cascade-remove extracted document attachments
 when parent is removed (#2432)

When a document (PPTX, DOCX, XLSX, ODP, ODT, ODS) is attached,
extracted slide images were left orphaned after removing the
parent text entry. This adds a sourceDocumentId field to
AttachedFile that links all entries from the same document
extraction, and cascades removal of all entries in the group
when any one is removed.

Fixes #2426

Co-authored-by: chiamsun <chiamsun@users.noreply.github.com>
---
 packages/ui/src/stores/types/sessionTypes.ts |  3 +
 packages/ui/src/sync/input-store.test.ts     | 94 ++++++++++++++++++++
 packages/ui/src/sync/input-store.ts          | 11 ++-
 3 files changed, 107 insertions(+), 1 deletion(-)

diff --git a/packages/ui/src/stores/types/sessionTypes.ts b/packages/ui/src/stores/types/sessionTypes.ts
index 4ad681e9..076ac900 100644
--- a/packages/ui/src/stores/types/sessionTypes.ts
+++ b/packages/ui/src/stores/types/sessionTypes.ts
@@ -21,6 +21,9 @@ export interface AttachedFile {
     serverPath?: string;
     vscodePath?: string;
     vscodeSource?: 'file' | 'selection';
+    /** Shared ID linking entries extracted from the same document (PPTX, DOCX, etc.).
+     *  Removing any entry with this ID cascades to all entries in the group. */
+    sourceDocumentId?: string;
 }
 
 export type EditPermissionMode = 'allow' | 'ask' | 'deny' | 'full';
diff --git a/packages/ui/src/sync/input-store.test.ts b/packages/ui/src/sync/input-store.test.ts
index db6a0740..33880228 100644
--- a/packages/ui/src/sync/input-store.test.ts
+++ b/packages/ui/src/sync/input-store.test.ts
@@ -276,4 +276,98 @@ describe("input-store attachments", () => {
     const textAttachment = useInputStore.getState().attachedFiles[1]
     expect((await textAttachment?.file.text())?.includes("[design-image-2.png]")).toBe(true)
   })
+
+  testWithMockFileReader("extracted document entries share a sourceDocumentId for cascade removal", async () => {
+    const archive = zipSync({
+      "word/document.xml": strToU8(`<w:document xmlns:w="w" xmlns:a="a" xmlns:r="r"><w:body><w:p><w:t>Diagram</w:t><a:blip r:embed="rId1"/></w:p></w:body></w:document>`),
+      "word/_rels/document.xml.rels": strToU8(`<Relationships><Relationship Id="rId1" Target="media/image.png" Type="image"/></Relationships>`),
+      "word/media/image.png": pngBytes,
+    })
+    const addPromise = useInputStore.getState().addAttachedFile(new File([archive], "design.docx"))
+
+    await waitForReaderCount(1)
+    resolveReader(pendingReaders[0], "data:text/plain;base64,RG9jdW1lbnQ=")
+    await waitForReaderCount(2)
+    resolveReader(pendingReaders[1], "data:image/png;base64,AQID")
+
+    expect(await addPromise).toBe(true)
+    const files = useInputStore.getState().attachedFiles
+    expect(files).toHaveLength(2)
+    expect(files[0].filename).toBe("design.docx")
+    expect(files[1].filename).toBe("design-image-1.png")
+
+    // All entries from the same document extraction share the same sourceDocumentId
+    expect(files[0].sourceDocumentId).toBeDefined()
+    expect(files[0].sourceDocumentId).toBe(files[1].sourceDocumentId)
+
+    // Removing any entry in the group cascade-removes all entries
+    useInputStore.getState().removeAttachedFile(files[0].id)
+    expect(useInputStore.getState().attachedFiles).toEqual([])
+  })
+
+  testWithMockFileReader("removing an extracted image child also cascade-removes the document group", async () => {
+    const archive = zipSync({
+      "word/document.xml": strToU8(`<w:document xmlns:w="w" xmlns:a="a" xmlns:r="r"><w:body><w:p><w:t>Diagram</w:t><a:blip r:embed="rId1"/></w:p></w:body></w:document>`),
+      "word/_rels/document.xml.rels": strToU8(`<Relationships><Relationship Id="rId1" Target="media/image.png" Type="image"/></Relationships>`),
+      "word/media/image.png": pngBytes,
+    })
+    const addPromise = useInputStore.getState().addAttachedFile(new File([archive], "design.docx"))
+
+    await waitForReaderCount(1)
+    resolveReader(pendingReaders[0], "data:text/plain;base64,RG9jdW1lbnQ=")
+    await waitForReaderCount(2)
+    resolveReader(pendingReaders[1], "data:image/png;base64,AQID")
+
+    expect(await addPromise).toBe(true)
+    const files = useInputStore.getState().attachedFiles
+    expect(files).toHaveLength(2)
+    expect(files[0].filename).toBe("design.docx")
+    expect(files[1].filename).toBe("design-image-1.png")
+
+    // Removing the image child also cascade-removes the entire group
+    useInputStore.getState().removeAttachedFile(files[1].id)
+    expect(useInputStore.getState().attachedFiles).toEqual([])
+  })
+
+  testWithMockFileReader("non-document attachments do not have sourceDocumentId and remove individually", async () => {
+    const addPromise = useInputStore.getState().addAttachedFile(
+      new File(["hello"], "hello.txt", { type: "text/plain" })
+    )
+    expect(pendingReaders).toHaveLength(1)
+    resolveReader(pendingReaders[0], "data:text/plain;base64,aGVsbG8=")
+
+    expect(await addPromise).toBe(true)
+    const files = useInputStore.getState().attachedFiles
+    expect(files).toHaveLength(1)
+    expect(files[0].sourceDocumentId).toBeUndefined()
+
+    useInputStore.getState().removeAttachedFile(files[0].id)
+    expect(useInputStore.getState().attachedFiles).toEqual([])
+  })
+
+  testWithMockFileReader("PPTX slide extraction cascades removal of all slide images", async () => {
+    const archive = zipSync({
+      "ppt/slides/slide1.xml": strToU8(`<p:sld xmlns:p="http://schemas.openxmlformats.org/presentationml/2006/main" xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"><p:cSld><p:spTree><p:pic><p:nvPicPr/><p:blipFill><a:blip r:embed="rId1"/></p:blipFill></p:pic></p:spTree></p:cSld></p:sld>`),
+      "ppt/slides/_rels/slide1.xml.rels": strToU8(`<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rId1" Target="../media/image1.png" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/image"/></Relationships>`),
+      "ppt/media/image1.png": pngBytes,
+    })
+    const addPromise = useInputStore.getState().addAttachedFile(new File([archive], "deck.pptx"))
+
+    await waitForReaderCount(1)
+    resolveReader(pendingReaders[0], "data:text/plain;base64,RG9jdW1lbnQ=")
+    await waitForReaderCount(2)
+    resolveReader(pendingReaders[1], "data:image/png;base64,AQID")
+
+    expect(await addPromise).toBe(true)
+    const files = useInputStore.getState().attachedFiles
+    expect(files).toHaveLength(2)
+    expect(files[0].filename).toBe("deck.pptx")
+    expect(files[1].filename).toBe("deck-image-1.png")
+    expect(files[0].sourceDocumentId).toBeDefined()
+    expect(files[0].sourceDocumentId).toBe(files[1].sourceDocumentId)
+
+    // Removing the text entry cascades to the slide image
+    useInputStore.getState().removeAttachedFile(files[0].id)
+    expect(useInputStore.getState().attachedFiles).toEqual([])
+  })
 })
diff --git a/packages/ui/src/sync/input-store.ts b/packages/ui/src/sync/input-store.ts
index 8f4d0635..9cc095c4 100644
--- a/packages/ui/src/sync/input-store.ts
+++ b/packages/ui/src/sync/input-store.ts
@@ -175,6 +175,8 @@ export const useInputStore = create<InputState>()((set, get) => ({
       if (hasGeneratedFilenameCollision(generatedFilenames, get().attachedFiles)) continue
 
       const attachedFiles: AttachedFile[] = []
+      const isDocumentExtraction = preparedFiles.length > 1
+      const sourceDocumentId = isDocumentExtraction ? `${Date.now()}-${Math.random().toString(36).slice(2)}` : undefined
       for (const prepared of preparedFiles) {
         let dataUrl: string
         try {
@@ -191,6 +193,7 @@ export const useInputStore = create<InputState>()((set, get) => ({
           filename: prepared.file.name,
           size: prepared.file.size,
           source: "local",
+          sourceDocumentId,
         })
       }
 
@@ -202,7 +205,13 @@ export const useInputStore = create<InputState>()((set, get) => ({
   },
 
   removeAttachedFile: (id) =>
-    set((s) => ({ attachedFiles: s.attachedFiles.filter((f) => f.id !== id) })),
+    set((s) => {
+      const target = s.attachedFiles.find((f) => f.id === id)
+      if (target?.sourceDocumentId) {
+        return { attachedFiles: s.attachedFiles.filter((f) => f.sourceDocumentId !== target.sourceDocumentId) }
+      }
+      return { attachedFiles: s.attachedFiles.filter((f) => f.id !== id) }
+    }),
 
   setAttachedFiles: (files) => {
     attachmentReadGeneration += 1

From 7e0e22f6e2e63b15287c4bc5fc91b406b37801b2 Mon Sep 17 00:00:00 2001
From: Mel0ny <72508862+mel0nyrame@users.noreply.github.com>
Date: Fri, 7 Aug 2026 03:59:08 +0800
Subject: [PATCH 43/57] fix(deps): upgrade adm-zip to 0.6.0 to fix
 GHSA-xcpc-8h2w-3j85 (#2643)

adm-zip <0.6.0 allows a crafted ZIP to trigger a ~4GB memory
allocation (GHSA-xcpc-8h2w-3j85). Bump the dependency in the web
and vscode packages to ^0.6.0. The new AdmZip(buffer) and
extractAllTo(dir, overwrite) APIs are unchanged, so no call-site
adaptation is needed.

Add a vitest regression test for the ClawdHub install path that
builds a real ZIP with adm-zip and asserts extractAllTo restores
files (including nested subdirectories) into the target skill dir.
---
 bun.lock                                      |   6 +-
 packages/vscode/package.json                  |   2 +-
 packages/web/package.json                     |   2 +-
 .../skills-catalog/clawdhub/install.test.js   | 100 ++++++++++++++++++
 4 files changed, 105 insertions(+), 5 deletions(-)
 create mode 100644 packages/web/server/lib/skills-catalog/clawdhub/install.test.js

diff --git a/bun.lock b/bun.lock
index cd8e95ab..1edf6ebc 100644
--- a/bun.lock
+++ b/bun.lock
@@ -240,7 +240,7 @@
       "dependencies": {
         "@openchamber/ui": "workspace:*",
         "@opencode-ai/sdk": "1.18.12",
-        "adm-zip": "^0.5.16",
+        "adm-zip": "^0.6.0",
         "jsonc-parser": "^3.3.1",
         "react": "^19.1.1",
         "react-dom": "^19.1.1",
@@ -268,7 +268,7 @@
         "@octokit/rest": "^22.0.1",
         "@opencode-ai/sdk": "1.18.12",
         "@simplewebauthn/server": "13.3.1",
-        "adm-zip": "^0.5.16",
+        "adm-zip": "^0.6.0",
         "bun-pty": "^0.4.5",
         "compression": "^1.8.1",
         "cron-parser": "^4.9.0",
@@ -1487,7 +1487,7 @@
 
     "acorn-jsx": ["acorn-jsx@5.3.2", "", { "peerDependencies": { "acorn": "^6.0.0 || ^7.0.0 || ^8.0.0" } }, "sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ=="],
 
-    "adm-zip": ["adm-zip@0.5.16", "", {}, "sha512-TGw5yVi4saajsSEgz25grObGHEUaDrniwvA2qwSC060KfqGPdglhvPMA2lPIoxs3PQIItj2iag35fONcQqgUaQ=="],
+    "adm-zip": ["adm-zip@0.6.0", "", {}, "sha512-XleryMhbuksdKtofnWZ9Sk+4CUTbms4Mb/EU32SZwToAyZ5RgVos/ki8n+yr0LWHOGKuakbXTuuYNHLQjhddgg=="],
 
     "agent-base": ["agent-base@7.1.4", "", {}, "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ=="],
 
diff --git a/packages/vscode/package.json b/packages/vscode/package.json
index feea88ca..7959a12d 100644
--- a/packages/vscode/package.json
+++ b/packages/vscode/package.json
@@ -245,7 +245,7 @@
   "dependencies": {
     "@openchamber/ui": "workspace:*",
     "@opencode-ai/sdk": "1.18.12",
-    "adm-zip": "^0.5.16",
+    "adm-zip": "^0.6.0",
     "jsonc-parser": "^3.3.1",
     "react": "^19.1.1",
     "react-dom": "^19.1.1",
diff --git a/packages/web/package.json b/packages/web/package.json
index 46b04352..51cfdbf5 100644
--- a/packages/web/package.json
+++ b/packages/web/package.json
@@ -27,7 +27,7 @@
     "@octokit/rest": "^22.0.1",
     "@opencode-ai/sdk": "1.18.12",
     "@simplewebauthn/server": "13.3.1",
-    "adm-zip": "^0.5.16",
+    "adm-zip": "^0.6.0",
     "bun-pty": "^0.4.5",
     "compression": "^1.8.1",
     "cron-parser": "^4.9.0",
diff --git a/packages/web/server/lib/skills-catalog/clawdhub/install.test.js b/packages/web/server/lib/skills-catalog/clawdhub/install.test.js
new file mode 100644
index 00000000..e57a29ba
--- /dev/null
+++ b/packages/web/server/lib/skills-catalog/clawdhub/install.test.js
@@ -0,0 +1,100 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import AdmZip from 'adm-zip';
+
+// Mock the ClawdHub network client so no real HTTP happens. The download
+// function is what feeds the ZIP buffer into adm-zip inside install.js.
+vi.mock('./api.js', () => ({
+  downloadClawdHubSkill: vi.fn(),
+  fetchClawdHubSkillInfo: vi.fn(),
+}));
+
+const { downloadClawdHubSkill } = await import('./api.js');
+const { installSkillsFromClawdHub } = await import('./install.js');
+
+/**
+ * Build a real ZIP archive with adm-zip (the dependency under test).
+ * Returns the raw Buffer, mirroring what downloadClawdHubSkill resolves to.
+ */
+function buildSkillZip(entries) {
+  const zip = new AdmZip();
+  for (const [entryName, content] of Object.entries(entries)) {
+    zip.addFile(entryName, Buffer.from(content, 'utf8'));
+  }
+  return zip.toBuffer();
+}
+
+describe('installSkillsFromClawdHub (adm-zip extraction path)', () => {
+  let userSkillDir;
+
+  beforeEach(async () => {
+    // Keep the target dir under os.tmpdir() so the temp->target rename in
+    // install.js stays on one filesystem (avoids EXDEV cross-device errors).
+    userSkillDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'clawdhub-test-skills-'));
+    vi.clearAllMocks();
+  });
+
+  afterEach(async () => {
+    await fs.promises.rm(userSkillDir, { recursive: true, force: true }).catch(() => {});
+  });
+
+  it('extracts a real ZIP (incl. nested subdirectories) into the target skill dir', async () => {
+    const skillMd = 'name: demo-skill\ndescription: adm-zip extraction regression guard\n';
+    const nested = 'nested file content for subdirectory extraction check\n';
+    downloadClawdHubSkill.mockResolvedValue(
+      buildSkillZip({ 'SKILL.md': skillMd, 'nested/data.txt': nested }),
+    );
+
+    const result = await installSkillsFromClawdHub({
+      scope: 'user',
+      targetSource: 'opencode',
+      userSkillDir,
+      // Non-'latest' version avoids the fetchClawdHubSkillInfo resolve branch.
+      selections: [{ clawdhub: { slug: 'demo-skill', version: '1.0.0' } }],
+    });
+
+    expect(result.ok).toBe(true);
+    expect(result.installed).toEqual([
+      { skillName: 'demo-skill', scope: 'user', source: 'opencode' },
+    ]);
+    expect(result.skipped).toEqual([]);
+
+    // downloadClawdHubSkill received the resolved (non-latest) version.
+    expect(downloadClawdHubSkill).toHaveBeenCalledWith('demo-skill', '1.0.0');
+
+    // adm-zip actually wrote the files, preserving the nested subdirectory.
+    const targetDir = path.join(userSkillDir, 'demo-skill');
+    const skillMdPath = path.join(targetDir, 'SKILL.md');
+    const nestedPath = path.join(targetDir, 'nested', 'data.txt');
+
+    expect(fs.existsSync(skillMdPath)).toBe(true);
+    expect(fs.existsSync(nestedPath)).toBe(true);
+    expect(fs.readFileSync(skillMdPath, 'utf8')).toBe(skillMd);
+    expect(fs.readFileSync(nestedPath, 'utf8')).toBe(nested);
+  });
+
+  it('skips a package whose extracted contents lack SKILL.md', async () => {
+    // Valid ZIP, but no SKILL.md at the root -> install.js must skip it and
+    // must NOT create the target dir. This exercises the extractAllTo path
+    // followed by the post-extraction validation.
+    downloadClawdHubSkill.mockResolvedValue(
+      buildSkillZip({ 'README.md': 'no skill manifest here\n' }),
+    );
+
+    const result = await installSkillsFromClawdHub({
+      scope: 'user',
+      targetSource: 'opencode',
+      userSkillDir,
+      selections: [{ clawdhub: { slug: 'broken-skill', version: '1.0.0' } }],
+    });
+
+    expect(result.ok).toBe(true);
+    expect(result.installed).toEqual([]);
+    expect(result.skipped).toEqual([
+      { skillName: 'broken-skill', reason: 'SKILL.md not found in downloaded package' },
+    ]);
+    expect(fs.existsSync(path.join(userSkillDir, 'broken-skill'))).toBe(false);
+  });
+});

From 61083c3915862610ea963d19272bacda72282352 Mon Sep 17 00:00:00 2001
From: CallMeBill <callmebill@billw.cn>
Date: Fri, 7 Aug 2026 04:20:40 +0800
Subject: [PATCH 44/57] feat: add fallback parsing for pairing connection
 payloads in old Android WebViews (#2611)

---
 packages/ui/src/apps/mobileQrScan.test.ts     | 36 ++++++++++++++++
 packages/ui/src/apps/mobileQrScan.ts          | 13 ++++--
 packages/ui/src/lib/connectionPayload.test.ts | 43 +++++++++++++++++++
 packages/ui/src/lib/connectionPayload.ts      | 32 ++++++++++++++
 4 files changed, 121 insertions(+), 3 deletions(-)

diff --git a/packages/ui/src/apps/mobileQrScan.test.ts b/packages/ui/src/apps/mobileQrScan.test.ts
index cba12b20..14ca8a70 100644
--- a/packages/ui/src/apps/mobileQrScan.test.ts
+++ b/packages/ui/src/apps/mobileQrScan.test.ts
@@ -83,6 +83,42 @@ describe('scanConnectionQr on Android', () => {
     expect(removeCalls).toBe(2);
   });
 
+  test('falls back to string parsing when the WebView URL parser rejects the link (old Android WebView)', async () => {
+    // Old Android WebViews resolve openchamber://connect?... with hostname "" and
+    // pathname "//connect", so the URL-based parse fails on an intact string. The test
+    // runtime's URL parser handles the canonical form fine, so simulate the rejection
+    // with a case variant the URL parser refuses while the string parser accepts.
+    const url = encodePairingConnectionPayload(buildPairingConnectionPayload({
+      pairingId: 'pair_abc',
+      secret: 'one-time',
+      candidates: [{ type: 'lan', url: 'http://192.168.1.20:4096', priority: 10 }],
+    }));
+    const mixedCase = url.replace('openchamber://connect', 'OpenChamber://CONNECT');
+    const listeners = new Map<string, (event: { barcodes?: Array<{ rawValue?: string }> }) => void>();
+    const plugin = {
+      requestPermissions: mock(async () => ({ camera: 'granted' })),
+      startScan: mock(async () => {
+        listeners.get('barcodesScanned')?.({ barcodes: [{ rawValue: mixedCase }] });
+      }),
+      stopScan: mock(async () => undefined),
+      addListener: mock((event: string, callback: (info: { barcodes?: Array<{ rawValue?: string }> }) => void) => {
+        listeners.set(event, callback);
+        return { remove: () => undefined };
+      }),
+    };
+    Object.defineProperty(globalThis, 'window', {
+      configurable: true,
+      value: { Capacitor: { getPlatform: () => 'android', Plugins: { BarcodeScanner: plugin } } },
+    });
+
+    const result = await scanConnectionQr();
+    expect(result.status).toBe('pairing');
+    if (result.status === 'pairing') {
+      expect(result.pairing.pairingId).toBe('pair_abc');
+      expect(result.pairing.candidates).toEqual([{ type: 'lan', url: 'http://192.168.1.20:4096', priority: 10 }]);
+    }
+  });
+
   test('stops scanning when the caller aborts', async () => {
     let stopCalls = 0;
     const stopScan = async () => { stopCalls += 1; };
diff --git a/packages/ui/src/apps/mobileQrScan.ts b/packages/ui/src/apps/mobileQrScan.ts
index e1980e99..2e54fec9 100644
--- a/packages/ui/src/apps/mobileQrScan.ts
+++ b/packages/ui/src/apps/mobileQrScan.ts
@@ -4,7 +4,7 @@
 // scan() activity, this path bundles the barcode model in the app and does not need
 // Google Play Services. iOS keeps the native ready-made scanner.
 
-import { parsePairingConnectionPayload, type PairingConnectionPayload } from '@/lib/connectionPayload';
+import { parsePairingConnectionPayload, parsePairingConnectionPayloadString, type PairingConnectionPayload } from '@/lib/connectionPayload';
 
 export type MobileConnectionPayload = {
   url: string;
@@ -65,8 +65,15 @@ export const parseConnectionPayload = (raw: string): MobileConnectionPayload | M
   return null;
 };
 
-const resultFromRawValue = (raw: string): QrScanResult => {
+const resultFromRawValue = (raw: string, options?: { pairingStringFallback?: boolean }): QrScanResult => {
   const payload = parseConnectionPayload(raw);
+  if (!payload && options?.pairingStringFallback) {
+    // Old Android WebViews resolve openchamber://… with hostname "" / pathname "//connect",
+    // so the URL-based parse above fails even though the scanned string is intact. Retry
+    // with the URL-API-free string parser before declaring the scan invalid.
+    const pairing = parsePairingConnectionPayloadString(raw);
+    if (pairing) return { status: 'pairing', pairing };
+  }
   if (!payload) return { status: 'invalid' };
   if ('pairing' in payload) return { status: 'pairing', ...payload };
   return { status: 'ok', ...payload };
@@ -100,7 +107,7 @@ const scanWithBundledAndroidScanner = async (
       Promise.resolve(plugin.addListener('barcodesScanned', ({ barcodes }) => {
         const barcode = barcodes?.[0];
         const raw = (barcode?.rawValue ?? barcode?.displayValue ?? '').trim();
-        if (raw) finish(resultFromRawValue(raw));
+        if (raw) finish(resultFromRawValue(raw, { pairingStringFallback: true }));
       })).then((handle) => { barcodeListener = handle; }),
       Promise.resolve(plugin.addListener('scanError', () => finish({ status: 'failed' })))
         .then((handle) => { errorListener = handle; }),
diff --git a/packages/ui/src/lib/connectionPayload.test.ts b/packages/ui/src/lib/connectionPayload.test.ts
index 5d11e173..e15105b5 100644
--- a/packages/ui/src/lib/connectionPayload.test.ts
+++ b/packages/ui/src/lib/connectionPayload.test.ts
@@ -4,6 +4,7 @@ import {
   buildPairingConnectionPayload,
   encodePairingConnectionPayload,
   parsePairingConnectionPayload,
+  parsePairingConnectionPayloadString,
 } from './connectionPayload';
 
 const hostEncPubJwk = { kty: 'EC', crv: 'P-256', x: 'eHhY', y: 'eVlZ' } as const;
@@ -103,3 +104,45 @@ describe('connection payload helpers', () => {
     expect(parsePairingConnectionPayload(`openchamber://connect?v=2&p=${expired}`)).toBeNull();
   });
 });
+
+describe('parsePairingConnectionPayloadString (Android WebView fallback)', () => {
+  const payload = buildPairingConnectionPayload({
+    pairingId: 'pair_123',
+    secret: 'one-time-secret',
+    label: 'Desktop',
+    candidates: [
+      { type: 'lan', url: 'http://192.168.1.20:4096', priority: 20 },
+      { type: 'relay', relayUrl: 'wss://relay.example/ws', serverId: 'srv_abc', hostEncPubJwk, priority: 30 },
+    ],
+  });
+  const encoded = encodePairingConnectionPayload(payload);
+
+  test('parses the canonical link identically to the URL-based parser', () => {
+    // Old Android WebViews resolve the same string with hostname "" / pathname "//connect";
+    // the string parser must not depend on the URL API to succeed.
+    expect(parsePairingConnectionPayloadString(encoded)).toEqual(parsePairingConnectionPayload(encoded));
+  });
+
+  test('recovers a link whose scheme/host case the URL parser would reject', () => {
+    const mixedCase = encoded.replace('openchamber://connect', 'OpenChamber://CONNECT');
+    expect(parsePairingConnectionPayload(mixedCase)).toBeNull();
+    expect(parsePairingConnectionPayloadString(mixedCase)).toEqual(parsePairingConnectionPayload(encoded));
+  });
+
+  test('tolerates a trailing slash and reordered query params', () => {
+    const trailingSlash = encoded.replace('openchamber://connect?', 'openchamber://connect/?');
+    expect(parsePairingConnectionPayloadString(trailingSlash)).toEqual(parsePairingConnectionPayload(encoded));
+
+    const p = encoded.slice(encoded.indexOf('p=') + 2);
+    expect(parsePairingConnectionPayloadString(`openchamber://connect?p=${p}&v=2`)).toEqual(parsePairingConnectionPayload(encoded));
+  });
+
+  test('still rejects non-pairing and malformed payloads', () => {
+    expect(parsePairingConnectionPayloadString('')).toBeNull();
+    expect(parsePairingConnectionPayloadString('hello world')).toBeNull();
+    expect(parsePairingConnectionPayloadString('openchamber://connect')).toBeNull();
+    expect(parsePairingConnectionPayloadString('openchamber:///connect?v=2&p=x')).toBeNull();
+    expect(parsePairingConnectionPayloadString('openchamber://connect?v=1&server=http%3A%2F%2F192.168.1.10%3A2606&token=t')).toBeNull();
+    expect(parsePairingConnectionPayloadString('openchamber://connect?v=2&p=not-json')).toBeNull();
+  });
+});
diff --git a/packages/ui/src/lib/connectionPayload.ts b/packages/ui/src/lib/connectionPayload.ts
index 88c7f1c7..d1c72526 100644
--- a/packages/ui/src/lib/connectionPayload.ts
+++ b/packages/ui/src/lib/connectionPayload.ts
@@ -212,3 +212,35 @@ export const parsePairingConnectionPayload = (value: string): PairingConnectionP
     return null;
   }
 };
+
+// URL-string-only sibling of parsePairingConnectionPayload. Old Android WebViews
+// (e.g. WebView 114) mis-parse non-special schemes: `new URL('openchamber://connect?...')`
+// yields hostname "" and pathname "//connect", so the URL-based parser above rejects a
+// perfectly valid pairing link. This parser never touches the URL/URLSearchParams APIs —
+// it matches the head with a regex and reads `v`/`p` straight off the query string.
+// Used by the Android QR-scan path after the standard parse fails; keeps every existing
+// validation (version, payload length, base64url, candidate normalization).
+export const parsePairingConnectionPayloadString = (value: string): PairingConnectionPayload | null => {
+  const trimmed = value.trim();
+  if (!trimmed || trimmed.length > MAX_PAIRING_PAYLOAD_LENGTH) return null;
+  const question = trimmed.indexOf('?');
+  if (question === -1 || !/^openchamber:\/\/connect\/?$/i.test(trimmed.slice(0, question))) return null;
+  let version: string | null = null;
+  let encoded: string | null = null;
+  for (const part of trimmed.slice(question + 1).split('&')) {
+    const eq = part.indexOf('=');
+    if (eq === -1) continue;
+    const key = part.slice(0, eq);
+    const value_ = part.slice(eq + 1);
+    if (key === 'v') version = value_;
+    else if (key === 'p') encoded = value_;
+  }
+  if (version !== '2' || !encoded || encoded.length > MAX_PAIRING_PAYLOAD_LENGTH) return null;
+  const decoded = base64UrlDecode(encoded);
+  if (!decoded || decoded.length > MAX_PAIRING_PAYLOAD_LENGTH) return null;
+  try {
+    return normalizePairingPayload(JSON.parse(decoded) as unknown);
+  } catch {
+    return null;
+  }
+};

From 27c46aa0b9ec742f9665c6a611121152dca21b91 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pascal=20Andr=C3=A9?= <pascalandr@gmail.com>
Date: Thu, 6 Aug 2026 22:31:51 +0200
Subject: [PATCH 45/57] fix(files): handle reveal launcher failures (#2490)

---
 packages/web/server/lib/fs/routes.js      | 29 ++++++-
 packages/web/server/lib/fs/routes.test.js | 98 +++++++++++++++++++++++
 2 files changed, 123 insertions(+), 4 deletions(-)

diff --git a/packages/web/server/lib/fs/routes.js b/packages/web/server/lib/fs/routes.js
index 95887cf5..62e897ac 100644
--- a/packages/web/server/lib/fs/routes.js
+++ b/packages/web/server/lib/fs/routes.js
@@ -382,6 +382,7 @@ export const registerFsRoutes = (app, dependencies) => {
     path,
     fsPromises,
     spawn,
+    platform = process.platform,
     crypto,
     normalizeDirectoryPath,
     resolveProjectDirectory,
@@ -393,6 +394,27 @@ export const registerFsRoutes = (app, dependencies) => {
     realpath: fsPromises.realpath.bind(fsPromises),
   });
 
+  const spawnDetached = (command, args) => new Promise((resolve, reject) => {
+    let child;
+    try {
+      child = spawn(command, args, { windowsHide: true, stdio: 'ignore', detached: true });
+    } catch (error) {
+      reject(new Error('Failed to launch file browser', { cause: error }));
+      return;
+    }
+    const onError = (error) => {
+      child.removeListener('spawn', onSpawn);
+      reject(new Error('Failed to launch file browser', { cause: error }));
+    };
+    const onSpawn = () => {
+      child.removeListener('error', onError);
+      child.unref();
+      resolve();
+    };
+    child.once('error', onError);
+    child.once('spawn', onSpawn);
+  });
+
   const execJobs = new Map();
   const commandTimeoutMs = createCommandTimeoutMs();
   const gitReadCacheTtlMs = createGitReadCacheTtlMs();
@@ -1134,13 +1156,12 @@ export const registerFsRoutes = (app, dependencies) => {
       const resolved = path.resolve(targetPath.trim());
       await fsPromises.access(resolved);
 
-      const platform = process.platform;
       if (platform === 'darwin') {
         const stat = await fsPromises.stat(resolved);
         if (stat.isDirectory()) {
-          spawn('open', [resolved], { windowsHide: true, stdio: 'ignore', detached: true }).unref();
+          await spawnDetached('open', [resolved]);
         } else {
-          spawn('open', ['-R', resolved], { windowsHide: true, stdio: 'ignore', detached: true }).unref();
+          await spawnDetached('open', ['-R', resolved]);
         }
       } else if (platform === 'win32') {
         const stat = await fsPromises.stat(resolved);
@@ -1164,7 +1185,7 @@ export const registerFsRoutes = (app, dependencies) => {
       } else {
         const stat = await fsPromises.stat(resolved);
         const dir = stat.isDirectory() ? resolved : path.dirname(resolved);
-        spawn('xdg-open', [dir], { windowsHide: true, stdio: 'ignore', detached: true }).unref();
+        await spawnDetached('xdg-open', [dir]);
       }
 
       return res.json({ success: true, path: resolved });
diff --git a/packages/web/server/lib/fs/routes.test.js b/packages/web/server/lib/fs/routes.test.js
index 576c0964..7f5e9832 100644
--- a/packages/web/server/lib/fs/routes.test.js
+++ b/packages/web/server/lib/fs/routes.test.js
@@ -200,6 +200,27 @@ const registerMkdir = (fsPromises) => {
   return getRoute('POST', '/api/fs/mkdir');
 };
 
+const registerReveal = ({ fsPromises, spawn, platform = 'linux' }) => {
+  const { app, getRoute } = createRouteRegistry();
+  registerFsRoutes(app, {
+    os: { homedir: () => '/home/user' },
+    path: path.posix,
+    fsPromises: {
+      realpath: async (targetPath) => targetPath,
+      ...fsPromises,
+    },
+    spawn,
+    platform,
+    crypto: { randomUUID: () => 'job-0' },
+    normalizeDirectoryPath: (p) => p,
+    resolveProjectDirectory: async () => ({ directory: '/repo' }),
+    buildAugmentedPath: () => '/usr/bin',
+    resolveGitBinaryForSpawn: () => 'git',
+    openchamberUserConfigRoot: '/home/user/.config',
+  });
+  return getRoute('POST', '/api/fs/reveal');
+};
+
 const callExec = async (handler, body) => {
   const res = createMockResponse();
   await handler({ body }, res);
@@ -230,6 +251,12 @@ const callMkdir = async (handler, body) => {
   return res;
 };
 
+const callReveal = async (handler, body) => {
+  const res = createMockResponse();
+  await handler({ body }, res);
+  return res;
+};
+
 describe('fs write', () => {
   it('does not rewrite a file when content is unchanged', async () => {
     const fsPromises = {
@@ -431,6 +458,77 @@ describe('fs read', () => {
   });
 });
 
+describe('fs reveal', () => {
+  it.each([
+    ['linux', 'xdg-open', ['/repo']],
+    ['darwin', 'open', ['-R', '/repo/file.txt']],
+  ])('returns a controlled error when the %s launcher is unavailable', async (platform, command, args) => {
+    const error = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const child = new EventEmitter();
+    child.unref = vi.fn();
+    const spawn = vi.fn(() => {
+      queueMicrotask(() => child.emit('error', Object.assign(new Error('not found'), { code: 'ENOENT' })));
+      return child;
+    });
+    const handler = registerReveal({
+      fsPromises: {
+        access: vi.fn(async () => undefined),
+        stat: vi.fn(async () => ({ isDirectory: () => false })),
+      },
+      spawn,
+      platform,
+    });
+
+    const res = await callReveal(handler, { path: '/repo/file.txt' });
+
+    expect(res.statusCode).toBe(500);
+    expect(res.body).toEqual({ error: 'Failed to launch file browser' });
+    expect(spawn).toHaveBeenCalledWith(command, args, { windowsHide: true, stdio: 'ignore', detached: true });
+    expect(child.unref).not.toHaveBeenCalled();
+    error.mockRestore();
+  });
+
+  it('unrefs a detached launcher only after it spawns successfully', async () => {
+    const child = new EventEmitter();
+    child.unref = vi.fn();
+    const spawn = vi.fn(() => {
+      queueMicrotask(() => child.emit('spawn'));
+      return child;
+    });
+    const handler = registerReveal({
+      fsPromises: {
+        access: vi.fn(async () => undefined),
+        stat: vi.fn(async () => ({ isDirectory: () => false })),
+      },
+      spawn,
+    });
+
+    const res = await callReveal(handler, { path: '/repo/file.txt' });
+
+    expect(res.body).toEqual({ success: true, path: '/repo/file.txt' });
+    expect(child.unref).toHaveBeenCalledOnce();
+  });
+
+  it('returns a controlled error when the launcher throws synchronously', async () => {
+    const error = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const spawnError = Object.assign(new Error('not found'), { code: 'ENOENT' });
+    const handler = registerReveal({
+      fsPromises: {
+        access: vi.fn(async () => undefined),
+        stat: vi.fn(async () => ({ isDirectory: () => false })),
+      },
+      spawn: vi.fn(() => { throw spawnError; }),
+    });
+
+    const res = await callReveal(handler, { path: '/repo/file.txt' });
+
+    expect(res.statusCode).toBe(500);
+    expect(res.body).toEqual({ error: 'Failed to launch file browser' });
+    expect(error).toHaveBeenCalledWith('Failed to reveal path:', expect.objectContaining({ cause: spawnError }));
+    error.mockRestore();
+  });
+});
+
 describe('fs exec git-read cache', () => {
   beforeEach(() => {
     delete process.env.OPENCHAMBER_GIT_READ_CACHE_TTL_MS;

From e8caed45c928aed5bbaead9c8f9681d92db41069 Mon Sep 17 00:00:00 2001
From: Bruno Fantauzzi <bftzia@gmail.com>
Date: Thu, 6 Aug 2026 17:47:30 -0300
Subject: [PATCH 46/57] fix: wait for worktree bootstrap before prompt
 dispatch; resolve session directory for send/fork (#2708)

---
 .../server/lib/openchamber-control/service.js | 25 +++++-
 .../lib/openchamber-control/service.test.js   | 37 +++++++++
 .../server/lib/openchamber-sessions/routes.js | 28 ++++++-
 .../lib/openchamber-sessions/routes.test.js   | 83 +++++++++++++++++++
 4 files changed, 170 insertions(+), 3 deletions(-)

diff --git a/packages/web/server/lib/openchamber-control/service.js b/packages/web/server/lib/openchamber-control/service.js
index ebdd0d72..25160bd4 100644
--- a/packages/web/server/lib/openchamber-control/service.js
+++ b/packages/web/server/lib/openchamber-control/service.js
@@ -240,10 +240,32 @@ export const createOpenChamberControlService = (dependencies) => {
     }
   };
 
+  // session.send/fork default the directory to the caller's context directory,
+  // which is wrong for sessions living in other worktrees: prompt_async then
+  // targets an instance that does not hold the session and the run dies with
+  // UnknownError. Resolve the target session's directory from the global
+  // session list when the caller did not scope explicitly.
+  const resolveSessionDirectory = async (sessionID) => {
+    try {
+      const client = await getClient();
+      const response = await client.experimental?.session?.list?.({});
+      const sessions = Array.isArray(response?.data) ? response.data : [];
+      const session = sessions.find((item) => item?.id === sessionID);
+      return asNonEmptyString(session?.directory) || null;
+    } catch {
+      return null;
+    }
+  };
+
   const executeSessionAction = async (action, input, contextDirectory, signal) => {
     if (input.timeout !== undefined && input.wait !== true) throw new OpenChamberControlError('timeout requires wait', 400);
     if (input.lastAssistant === true && input.wait !== true) throw new OpenChamberControlError('lastAssistant requires wait', 400);
-    const directory = asNonEmptyString(input.directory) || (!input.projectId ? asNonEmptyString(contextDirectory) : null);
+    const sessionID = asNonEmptyString(input.sessionId);
+    let directory = asNonEmptyString(input.directory) || (!input.projectId ? asNonEmptyString(contextDirectory) : null);
+    if (sessionID && action !== 'session.create' && !asNonEmptyString(input.directory) && !input.projectId) {
+      const resolvedSessionDirectory = await resolveSessionDirectory(sessionID);
+      if (resolvedSessionDirectory) directory = resolvedSessionDirectory;
+    }
     const payload = {
       ...(directory ? { directory } : {}),
       ...(asNonEmptyString(input.projectId) ? { projectId: input.projectId.trim() } : {}),
@@ -262,7 +284,6 @@ export const createOpenChamberControlService = (dependencies) => {
       ...(typeof input.setUpstream === 'boolean' ? { setUpstream: input.setUpstream } : {}),
       ...(asNonEmptyString(input.messageId) ? { messageId: input.messageId.trim() } : {}),
     };
-    const sessionID = asNonEmptyString(input.sessionId);
     const startedAt = now();
     let result;
     if (action === 'session.create') {
diff --git a/packages/web/server/lib/openchamber-control/service.test.js b/packages/web/server/lib/openchamber-control/service.test.js
index a9a1be47..5cede73c 100644
--- a/packages/web/server/lib/openchamber-control/service.test.js
+++ b/packages/web/server/lib/openchamber-control/service.test.js
@@ -132,6 +132,43 @@ describe('OpenChamber control service', () => {
     expect(sessionService[method]).toHaveBeenCalledWith('ses_1', { directory: '/repo', prompt: 'Continue' });
   });
 
+  it('resolves the target session directory from the global session list when send omits it', async () => {
+    const { service, sessionService, client } = createService({
+      createClient: () => ({
+        ...client,
+        experimental: {
+          session: {
+            list: vi.fn(async () => ({
+              data: [
+                { id: 'ses_other', directory: '/repo/worktrees/other' },
+                { id: 'ses_target', directory: '/repo/worktrees/target' },
+              ],
+            })),
+          },
+        },
+      }),
+    });
+    sessionService.send.mockResolvedValue({ sessionId: 'ses_target', directory: '/repo/worktrees/target', promptDispatched: true });
+
+    await service.execute('session.send', { sessionId: 'ses_target', prompt: 'Continue' }, '/repo');
+
+    expect(sessionService.send).toHaveBeenCalledWith('ses_target', { directory: '/repo/worktrees/target', prompt: 'Continue' });
+  });
+
+  it('falls back to the context directory when the session is not in the global list', async () => {
+    const { service, sessionService, client } = createService({
+      createClient: () => ({
+        ...client,
+        experimental: { session: { list: vi.fn(async () => ({ data: [] })) } },
+      }),
+    });
+    sessionService.send.mockResolvedValue({ sessionId: 'ses_unknown', directory: '/repo', promptDispatched: true });
+
+    await service.execute('session.send', { sessionId: 'ses_unknown', prompt: 'Continue' }, '/repo');
+
+    expect(sessionService.send).toHaveBeenCalledWith('ses_unknown', { directory: '/repo', prompt: 'Continue' });
+  });
+
   it('waits past initial idle until a completed assistant result appears', async () => {
     let timestamp = 1000;
     const { service, client, sessionService } = createService({
diff --git a/packages/web/server/lib/openchamber-sessions/routes.js b/packages/web/server/lib/openchamber-sessions/routes.js
index 0c82b1e0..f7ca1304 100644
--- a/packages/web/server/lib/openchamber-sessions/routes.js
+++ b/packages/web/server/lib/openchamber-sessions/routes.js
@@ -1,6 +1,6 @@
 import express from 'express';
 import { createOpencodeClient } from '@opencode-ai/sdk/v2';
-import { createWorktree } from '../git/index.js';
+import { createWorktree, getWorktreeBootstrapStatus } from '../git/index.js';
 import { expandSnippets } from '../opencode/snippets.js';
 import { expandCommandGoalObjective, parseScheduledCommandPrompt } from '../scheduled-tasks/runtime.js';
 import { buildGoalIntroText, createSessionGoal } from '../session-goal/create.js';
@@ -275,6 +275,31 @@ const resolveRequestedDirectory = async ({ payload, readSettingsFromDiskMigrated
 const PROMPT_LANDED_TIMEOUT_MS = 5_000;
 const PROMPT_LANDED_POLL_MS = 150;
 
+// createWorktree returns while the worktree is still being populated in the
+// background (git reset --hard after a --no-checkout add). Dispatching a
+// prompt into a half-populated directory makes opencode's run die with
+// UnknownError (agent and config files are not there yet), so wait until the
+// bootstrap reaches git-ready (population done) or fails before creating the
+// session and dispatching.
+const WORKTREE_BOOTSTRAP_TIMEOUT_MS = 60_000;
+const WORKTREE_BOOTSTRAP_POLL_MS = 150;
+
+const waitForWorktreeBootstrapReady = async ({ directory }) => {
+  const deadline = Date.now() + WORKTREE_BOOTSTRAP_TIMEOUT_MS;
+  for (;;) {
+    const status = await getWorktreeBootstrapStatus(directory);
+    if (status?.status === 'failed') {
+      throw new OpenChamberControlError(`Worktree bootstrap failed: ${status.error || 'unknown error'}`, 500);
+    }
+    const phase = status?.phase;
+    if (status?.status === 'ready' || phase === 'git-ready' || phase === 'setup-ready') return;
+    if (Date.now() >= deadline) {
+      throw new OpenChamberControlError('Timed out waiting for the worktree bootstrap', 500);
+    }
+    await new Promise((resolve) => setTimeout(resolve, WORKTREE_BOOTSTRAP_POLL_MS));
+  }
+};
+
 const latestUserMessageID = async ({ client, sessionID, directory }) => {
   let response;
   try {
@@ -579,6 +604,7 @@ export const createOpenChamberSessionService = (dependencies) => {
     if (worktreeInput) {
       worktree = await createWorktree(resolvedDirectory.directory, worktreeInput);
       sessionDirectory = worktree.path;
+      await waitForWorktreeBootstrapReady({ directory: sessionDirectory });
     }
 
     const baseUrl = buildOpenCodeUrl('/', '').replace(/\/$/, '');
diff --git a/packages/web/server/lib/openchamber-sessions/routes.test.js b/packages/web/server/lib/openchamber-sessions/routes.test.js
index 8b964fb6..3f6fbe5b 100644
--- a/packages/web/server/lib/openchamber-sessions/routes.test.js
+++ b/packages/web/server/lib/openchamber-sessions/routes.test.js
@@ -8,6 +8,12 @@ const createWorktreeMock = vi.fn(async () => ({
   branch: 'openchamber/side-task',
   path: '/repo/worktrees/side-task',
 }));
+const getWorktreeBootstrapStatusMock = vi.fn(async () => ({
+  status: 'ready',
+  phase: 'setup-ready',
+  error: null,
+  updatedAt: Date.now(),
+}));
 const sessionCreateMock = vi.fn(async () => ({ data: { id: 'ses_123' } }));
 const sessionForkMock = vi.fn(async () => ({ data: { id: 'ses_fork', title: 'Forked session' } }));
 const sessionMessagesMock = vi.fn(async () => ({ data: [] }));
@@ -61,6 +67,7 @@ const selectionInputResponse = (url) => {
 const sessionCommandMock = vi.fn(async () => ({ data: {} }));
 const commandListMock = vi.fn(async () => ({ data: [] }));
 globalThis.__openchamberCreateWorktreeMock = createWorktreeMock;
+globalThis.__openchamberGetWorktreeBootstrapStatusMock = getWorktreeBootstrapStatusMock;
 
 let registerOpenChamberSessionRoutes;
 
@@ -80,6 +87,7 @@ vi.mock('@opencode-ai/sdk/v2', () => ({
 
 vi.mock('../git/index.js', () => ({
   createWorktree: (...args) => globalThis.__openchamberCreateWorktreeMock(...args),
+  getWorktreeBootstrapStatus: (...args) => globalThis.__openchamberGetWorktreeBootstrapStatusMock(...args),
 }));
 
 const createApp = (overrides = {}, options = {}) => {
@@ -107,6 +115,13 @@ describe('openchamber session routes', () => {
 
   beforeEach(() => {
     createWorktreeMock.mockClear();
+    getWorktreeBootstrapStatusMock.mockClear();
+    getWorktreeBootstrapStatusMock.mockImplementation(async () => ({
+      status: 'ready',
+      phase: 'setup-ready',
+      error: null,
+      updatedAt: Date.now(),
+    }));
     sessionCreateMock.mockClear();
     sessionForkMock.mockClear();
     existingSessionMessages = [];
@@ -366,6 +381,74 @@ describe('openchamber session routes', () => {
     }
   });
 
+  it('waits for the worktree bootstrap to complete before creating the session', async () => {
+    const statuses = [
+      { status: 'pending', phase: 'directory-created', error: null, updatedAt: 1 },
+      { status: 'pending', phase: 'git-ready', error: null, updatedAt: 2 },
+      { status: 'ready', phase: 'setup-ready', error: null, updatedAt: 3 },
+    ];
+    getWorktreeBootstrapStatusMock.mockImplementation(async () => statuses.shift() || statuses[statuses.length - 1]);
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = vi.fn(async (url) => {
+      if (String(url).includes('/prompt_async')) {
+        return { ok: true, text: async () => '' };
+      }
+      return { ok: true, json: async () => ({ id: 'ses_123' }) };
+    });
+    try {
+      const { app } = createApp();
+      const response = await request(app)
+        .post('/api/openchamber/sessions')
+        .send({
+          directory: '/repo/app',
+          worktree: { name: 'side-task' },
+          prompt: 'Run this',
+          model: 'openai/gpt-5.5',
+        })
+        .expect(200);
+
+      expect(response.body.promptDispatched).toBe(true);
+      const sessionCreateCalls = globalThis.fetch.mock.calls.filter(([url]) => String(url).includes('/session?directory'));
+      const promptCalls = globalThis.fetch.mock.calls.filter(([url]) => String(url).includes('/prompt_async'));
+      expect(sessionCreateCalls.length).toBeGreaterThanOrEqual(1);
+      expect(promptCalls.length).toBeGreaterThanOrEqual(1);
+      const createIndex = globalThis.fetch.mock.calls.indexOf(sessionCreateCalls[0]);
+      const promptIndex = globalThis.fetch.mock.calls.indexOf(promptCalls[0]);
+      expect(getWorktreeBootstrapStatusMock).toHaveBeenCalled();
+      expect(createIndex).toBeGreaterThan(-1);
+      expect(promptIndex).toBeGreaterThan(createIndex);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  it('fails the create when the worktree bootstrap failed', async () => {
+    getWorktreeBootstrapStatusMock.mockImplementation(async () => ({
+      status: 'failed',
+      phase: 'directory-created',
+      error: 'branch already exists',
+      updatedAt: Date.now(),
+    }));
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = vi.fn(async (url) => ({ ok: true, json: async () => ({ id: 'ses_123' }) }));
+    try {
+      const { app } = createApp();
+      await request(app)
+        .post('/api/openchamber/sessions')
+        .send({
+          directory: '/repo/app',
+          worktree: { name: 'side-task' },
+          prompt: 'Run this',
+          model: 'openai/gpt-5.5',
+        })
+        .expect(500, { error: 'Worktree bootstrap failed: branch already exists' });
+      const promptCalls = globalThis.fetch.mock.calls.filter(([url]) => String(url).includes('/prompt_async'));
+      expect(promptCalls.length).toBe(0);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
   it('sends a goal prompt to an existing session after creating goal metadata', async () => {
     const originalFetch = globalThis.fetch;
     const fetchMock = vi.fn(async (url) => selectionInputResponse(url) || { ok: true, text: async () => '' });

From 668a6f54fecb08e5ebf3cadef682c88a416de550 Mon Sep 17 00:00:00 2001
From: Syu <62822461+SYU8384@users.noreply.github.com>
Date: Fri, 7 Aug 2026 06:10:29 +0900
Subject: [PATCH 47/57] fix(web): update foreground systemd services safely
 (#2542)

* fix(web): update foreground systemd services safely

* clarify desktop and remote updates

* Revert "clarify desktop and remote updates"

This reverts commit aaf4516277de003e132d549d5281811fae96cfd5.

* test-web-systemd-updates
---
 .../web/server/lib/opencode/DOCUMENTATION.md  |   3 +
 .../server/lib/opencode/openchamber-routes.js |  69 ++++++++-
 .../lib/opencode/openchamber-routes.test.js   | 141 ++++++++++++++++++
 3 files changed, 212 insertions(+), 1 deletion(-)
 create mode 100644 packages/web/server/lib/opencode/openchamber-routes.test.js

diff --git a/packages/web/server/lib/opencode/DOCUMENTATION.md b/packages/web/server/lib/opencode/DOCUMENTATION.md
index 3996860f..bbb5137f 100644
--- a/packages/web/server/lib/opencode/DOCUMENTATION.md
+++ b/packages/web/server/lib/opencode/DOCUMENTATION.md
@@ -343,6 +343,9 @@ an authoritative loopback callback URL even when OpenChamber binds port `0`.
 - `registerOpenChamberRoutes(app, dependencies)`: registers OpenChamber endpoints:
   - `GET /api/openchamber/update-check`
   - `POST /api/openchamber/update-install`
+    - Foreground servers running under a systemd user unit queue installation in
+      a separate transient unit and restart the configured service afterwards.
+      `OPENCHAMBER_SYSTEMD_UNIT` overrides the default `openchamber.service`.
   - `GET /api/openchamber/models-metadata`
   - `GET /api/zen/models`
 
diff --git a/packages/web/server/lib/opencode/openchamber-routes.js b/packages/web/server/lib/opencode/openchamber-routes.js
index 4c3d88f5..a618e731 100644
--- a/packages/web/server/lib/opencode/openchamber-routes.js
+++ b/packages/web/server/lib/opencode/openchamber-routes.js
@@ -1,3 +1,21 @@
+const SYSTEMD_SERVICE_UNIT_PATTERN = /^[A-Za-z0-9:_.@-]+\.service$/;
+
+function resolveSystemdServiceUnit(environment) {
+  if (!environment.INVOCATION_ID) {
+    return null;
+  }
+
+  const configuredUnit = typeof environment.OPENCHAMBER_SYSTEMD_UNIT === 'string'
+    ? environment.OPENCHAMBER_SYSTEMD_UNIT.trim()
+    : '';
+  const unit = configuredUnit || 'openchamber.service';
+  return SYSTEMD_SERVICE_UNIT_PATTERN.test(unit) ? unit : null;
+}
+
+function quotePosixShell(value) {
+  return `'${String(value).replace(/'/g, "'\\''")}'`;
+}
+
 export const registerOpenChamberRoutes = (app, dependencies) => {
   const {
     fs,
@@ -54,7 +72,7 @@ export const registerOpenChamberRoutes = (app, dependencies) => {
 
   app.post('/api/openchamber/update-install', async (_req, res) => {
     try {
-      const { spawn: spawnChild } = await import('child_process');
+      const { spawn: spawnChild, spawnSync } = await import('child_process');
       const {
         checkForUpdates,
         getUpdateCommand,
@@ -110,6 +128,55 @@ export const registerOpenChamberRoutes = (app, dependencies) => {
       }
       const launchMode = storedOptions.launchMode === 'foreground' ? 'foreground' : 'daemon';
       const isForegroundService = launchMode === 'foreground';
+      const systemdServiceUnit = isForegroundService ? resolveSystemdServiceUnit(process.env) : null;
+
+      if (isForegroundService) {
+        if (!systemdServiceUnit) {
+          return res.status(409).json({
+            error: 'Foreground servers must be updated by their service manager. Set OPENCHAMBER_SYSTEMD_UNIT when running under systemd, or run openchamber update and restart the service.',
+          });
+        }
+
+        const updateJobName = `openchamber-update-${Date.now()}`;
+        const updateLogPath = `journalctl --user-unit ${updateJobName}.service`;
+        const updateScript = [
+          'set -eu',
+          updateCmd,
+          `systemctl --user restart ${quotePosixShell(systemdServiceUnit)}`,
+        ].join('\n');
+        const systemdRun = spawnSync('systemd-run', [
+          '--user',
+          `--unit=${updateJobName}`,
+          '--collect',
+          '--service-type=exec',
+          `--setenv=PATH=${process.env.PATH || ''}`,
+          '/bin/sh',
+          '-c',
+          updateScript,
+        ], {
+          encoding: 'utf8',
+          stdio: ['ignore', 'pipe', 'pipe'],
+          timeout: 5000,
+        });
+
+        if (systemdRun.status !== 0) {
+          const detail = (systemdRun.stderr || systemdRun.stdout || '').trim();
+          return res.status(409).json({
+            error: detail || `Could not queue update job for ${systemdServiceUnit}`,
+          });
+        }
+
+        return res.json({
+          success: true,
+          message: 'Update queued; OpenChamber will restart after installation completes',
+          version: updateInfo.version,
+          packageManager: pm,
+          autoRestart: true,
+          restartManager: 'systemd',
+          jobId: updateJobName,
+          logPath: updateLogPath,
+        });
+      }
 
       const isWindows = process.platform === 'win32';
       const quotePosix = (value) => `'${String(value).replace(/'/g, "'\\''")}'`;
diff --git a/packages/web/server/lib/opencode/openchamber-routes.test.js b/packages/web/server/lib/opencode/openchamber-routes.test.js
new file mode 100644
index 00000000..6b5ac534
--- /dev/null
+++ b/packages/web/server/lib/opencode/openchamber-routes.test.js
@@ -0,0 +1,141 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import express from 'express';
+import path from 'node:path';
+import request from 'supertest';
+
+vi.mock('child_process', () => ({
+  spawn: vi.fn(),
+  spawnSync: vi.fn(),
+}));
+
+vi.mock('../package-manager.js', () => ({
+  checkForUpdates: vi.fn(),
+  getUpdateCommand: vi.fn(),
+  detectPackageManagerDetails: vi.fn(),
+}));
+
+const childProcess = await import('child_process');
+const packageManager = await import('../package-manager.js');
+const { registerOpenChamberRoutes } = await import('./openchamber-routes.js');
+
+const createApp = ({ environment = {}, storedOptions = {} } = {}) => {
+  const app = express();
+  const dependencies = {
+    fs: {
+      existsSync: vi.fn(() => false),
+      promises: {
+        readFile: vi.fn(async () => JSON.stringify({
+          launchMode: 'foreground',
+          port: 7897,
+          ...storedOptions,
+        })),
+      },
+    },
+    path,
+    process: {
+      env: environment,
+      platform: 'linux',
+      execPath: '/usr/bin/node',
+    },
+    server: {
+      address: () => ({ port: 7897 }),
+    },
+    __dirname: '/opt/openchamber/server',
+    openchamberDataDir: '/tmp/openchamber',
+    modelsDevApiUrl: 'https://models.example.test',
+    modelsMetadataCacheTtl: 0,
+    readSettingsFromDiskMigrated: vi.fn(),
+    fetchFreeZenModels: vi.fn(),
+    getCachedZenModels: vi.fn(),
+  };
+
+  registerOpenChamberRoutes(app, dependencies);
+  return { app, dependencies };
+};
+
+beforeEach(() => {
+  packageManager.checkForUpdates.mockResolvedValue({
+    available: true,
+    version: '1.17.1',
+  });
+  packageManager.detectPackageManagerDetails.mockReturnValue({
+    packageManager: 'npm',
+  });
+  packageManager.getUpdateCommand.mockReturnValue('npm install -g @openchamber/web@latest');
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.clearAllMocks();
+});
+
+describe('OpenChamber foreground update route', () => {
+  it('rejects a foreground update when the server is not owned by systemd', async () => {
+    const { app } = createApp();
+
+    await request(app)
+      .post('/api/openchamber/update-install')
+      .expect(409, {
+        error: 'Foreground servers must be updated by their service manager. Set OPENCHAMBER_SYSTEMD_UNIT when running under systemd, or run openchamber update and restart the service.',
+      });
+
+    expect(childProcess.spawnSync).not.toHaveBeenCalled();
+  });
+
+  it('rejects an unsafe systemd unit override before starting an update job', async () => {
+    const { app } = createApp({
+      environment: {
+        INVOCATION_ID: 'systemd-invocation',
+        OPENCHAMBER_SYSTEMD_UNIT: 'openchamber.service; rm -rf /',
+      },
+    });
+
+    await request(app)
+      .post('/api/openchamber/update-install')
+      .expect(409, {
+        error: 'Foreground servers must be updated by their service manager. Set OPENCHAMBER_SYSTEMD_UNIT when running under systemd, or run openchamber update and restart the service.',
+      });
+
+    expect(childProcess.spawnSync).not.toHaveBeenCalled();
+  });
+
+  it('queues the install in a transient systemd unit and returns its job identifier', async () => {
+    vi.spyOn(Date, 'now').mockReturnValue(1_700_000_000_000);
+    childProcess.spawnSync.mockReturnValue({ status: 0, stdout: '', stderr: '' });
+    const { app } = createApp({
+      environment: {
+        INVOCATION_ID: 'systemd-invocation',
+        OPENCHAMBER_SYSTEMD_UNIT: 'openchamber@wsl.service',
+        PATH: '/home/syu/.npm-global/bin:/usr/bin:/bin',
+      },
+    });
+
+    await request(app)
+      .post('/api/openchamber/update-install')
+      .expect(200, {
+        success: true,
+        message: 'Update queued; OpenChamber will restart after installation completes',
+        version: '1.17.1',
+        packageManager: 'npm',
+        autoRestart: true,
+        restartManager: 'systemd',
+        jobId: 'openchamber-update-1700000000000',
+        logPath: 'journalctl --user-unit openchamber-update-1700000000000.service',
+      });
+
+    expect(childProcess.spawnSync).toHaveBeenCalledWith('systemd-run', [
+      '--user',
+      '--unit=openchamber-update-1700000000000',
+      '--collect',
+      '--service-type=exec',
+      '--setenv=PATH=/home/syu/.npm-global/bin:/usr/bin:/bin',
+      '/bin/sh',
+      '-c',
+      "set -eu\nnpm install -g @openchamber/web@latest\nsystemctl --user restart 'openchamber@wsl.service'",
+    ], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 5000,
+    });
+  });
+});

From 834d2edb879e3bddf8ed0a7a4360ec9c4634872c Mon Sep 17 00:00:00 2001
From: Serhii Dziupin <serkraser@gmail.com>
Date: Fri, 7 Aug 2026 00:25:57 +0300
Subject: [PATCH 48/57] feat(ui,server): surface active instance service URLs
 in About settings (#2669)

Show the running instance's local server URL and tunnel URL (when a
tunnel is active) as labeled, click-to-open buttons on the About page.
/api/system/info now reports the instance port and tunnel URL, resolved
lazily from the tunnel runtime so each Git-worktree instance identifies
itself in the UI without parsing terminal output.

Refs OPE-194
---
 .../sections/openchamber/AboutSettings.tsx    |   7 ++
 .../openchamber/InstanceServiceUrls.tsx       | 106 ++++++++++++++++++
 .../ui/src/lib/i18n/messages/de.settings.ts   |   3 +
 .../ui/src/lib/i18n/messages/en.settings.ts   |   3 +
 .../ui/src/lib/i18n/messages/es.settings.ts   |   3 +
 .../ui/src/lib/i18n/messages/fr.settings.ts   |   3 +
 .../ui/src/lib/i18n/messages/ja.settings.ts   |   3 +
 .../ui/src/lib/i18n/messages/ko.settings.ts   |   3 +
 .../ui/src/lib/i18n/messages/pl.settings.ts   |   3 +
 .../src/lib/i18n/messages/pt-BR.settings.ts   |   3 +
 .../ui/src/lib/i18n/messages/uk.settings.ts   |   3 +
 .../src/lib/i18n/messages/zh-CN.settings.ts   |   3 +
 .../src/lib/i18n/messages/zh-TW.settings.ts   |   3 +
 packages/web/server/index.js                  |  14 +++
 .../server/lib/opencode/bootstrap-runtime.js  |   4 +
 .../web/server/lib/opencode/core-routes.js    |   8 ++
 .../server/lib/opencode/core-routes.test.js   |  42 +++++++
 17 files changed, 214 insertions(+)
 create mode 100644 packages/ui/src/components/sections/openchamber/InstanceServiceUrls.tsx

diff --git a/packages/ui/src/components/sections/openchamber/AboutSettings.tsx b/packages/ui/src/components/sections/openchamber/AboutSettings.tsx
index 6bffa19c..95488727 100644
--- a/packages/ui/src/components/sections/openchamber/AboutSettings.tsx
+++ b/packages/ui/src/components/sections/openchamber/AboutSettings.tsx
@@ -9,6 +9,7 @@ import { Icon } from "@/components/icon/Icon";
 import { OpenChamberLogo } from '@/components/ui/OpenChamberLogo';
 import { useI18n } from '@/lib/i18n';
 import { runtimeFetch } from '@/lib/runtime-fetch';
+import { InstanceServiceUrls } from './InstanceServiceUrls';
 import {
   SettingsSection,
   SETTINGS_BRAND_TITLE_CLASS,
@@ -135,6 +136,7 @@ export const AboutSettings: React.FC<AboutSettingsProps> = ({ initialUpdateDialo
             <p>{t('aboutDialog.openChamberVersionLabel', { version: currentVersion })}</p>
             <p>{t('aboutDialog.openCodeVersionLabel', { version: openCodeVersion || t('settings.openchamber.about.state.unknown') })}</p>
           </div>
+          <InstanceServiceUrls />
         </div>
 
         <div className="flex justify-center">
@@ -278,6 +280,11 @@ export const AboutSettings: React.FC<AboutSettingsProps> = ({ initialUpdateDialo
           </div>
         )}
 
+        <div className="flex flex-col gap-2 border-b border-border/40 px-4 py-3 @xl:flex-row @xl:items-center @xl:justify-between">
+          <span className={SETTINGS_FIELD_LABEL_CLASS}>{t('settings.openchamber.about.field.instanceUrls')}</span>
+          <InstanceServiceUrls />
+        </div>
+
         <div className="flex items-center gap-4 px-4 py-4">
           <a
             href={GITHUB_URL}
diff --git a/packages/ui/src/components/sections/openchamber/InstanceServiceUrls.tsx b/packages/ui/src/components/sections/openchamber/InstanceServiceUrls.tsx
new file mode 100644
index 00000000..495a061e
--- /dev/null
+++ b/packages/ui/src/components/sections/openchamber/InstanceServiceUrls.tsx
@@ -0,0 +1,106 @@
+import React from 'react';
+import { useI18n } from '@/lib/i18n';
+import { runtimeFetch } from '@/lib/runtime-fetch';
+import { openExternalUrl } from '@/lib/url';
+import { Button } from '@/components/ui/button';
+import { Icon } from '@/components/icon/Icon';
+
+type InstanceServiceInfo = {
+  port: number | null;
+  tunnelUrl: string | null;
+};
+
+type InstanceService = {
+  key: string;
+  label: string;
+  url: string;
+};
+
+/**
+ * Shows the active instance's service URLs (local server port + tunnel URL,
+ * when a tunnel is active) as labeled buttons that open the URL in the
+ * browser. The data comes from `/api/system/info`, which the server derives
+ * from its own runtime state — this is what makes each Git-worktree instance
+ * distinguishable in the UI without reading terminal output.
+ *
+ * The section stays hidden when the endpoint is unavailable or reports no
+ * port/tunnel (e.g. VS Code runtime), so a failed fetch never renders stale
+ * or wrong URLs.
+ */
+export const InstanceServiceUrls: React.FC = () => {
+  const { t } = useI18n();
+  const [info, setInfo] = React.useState<InstanceServiceInfo | null>(null);
+
+  React.useEffect(() => {
+    let cancelled = false;
+    const controller = typeof AbortController !== 'undefined' ? new AbortController() : undefined;
+
+    const load = async () => {
+      try {
+        const response = await runtimeFetch('/api/system/info', {
+          signal: controller?.signal,
+          headers: { Accept: 'application/json' },
+        });
+        if (!response.ok) return;
+        const data = await response.json().catch(() => null) as { port?: unknown; tunnelUrl?: unknown } | null;
+        if (!data || cancelled) return;
+        const port = typeof data.port === 'number' && Number.isFinite(data.port) && data.port > 0 ? data.port : null;
+        const tunnelUrl = typeof data.tunnelUrl === 'string' && data.tunnelUrl.trim().length > 0
+          ? data.tunnelUrl.trim()
+          : null;
+        setInfo({ port, tunnelUrl });
+      } catch {
+        // Best-effort: a failed fetch keeps the section hidden instead of
+        // showing data we cannot verify.
+      }
+    };
+
+    void load();
+
+    return () => {
+      cancelled = true;
+      controller?.abort();
+    };
+  }, []);
+
+  const services: InstanceService[] = [];
+  if (info?.port !== null && info?.port !== undefined) {
+    services.push({
+      key: 'application',
+      label: t('settings.openchamber.about.field.applicationUrl'),
+      url: `http://localhost:${info.port}/`,
+    });
+  }
+  if (info?.tunnelUrl) {
+    services.push({
+      key: 'tunnel',
+      label: t('settings.openchamber.about.field.tunnelUrl'),
+      url: info.tunnelUrl,
+    });
+  }
+
+  if (services.length === 0) {
+    return null;
+  }
+
+  return (
+    <div className="flex flex-wrap items-center gap-2">
+      {services.map((service) => (
+        <Button
+          key={service.key}
+          type="button"
+          variant="outline"
+          size="sm"
+          title={service.label}
+          className="max-w-full gap-1.5 px-2.5"
+          onClick={() => {
+            void openExternalUrl(service.url);
+          }}
+        >
+          <Icon name="external-link" className="size-3.5 shrink-0" />
+          <span className="max-w-64 truncate font-mono typography-micro">{service.url}</span>
+        </Button>
+      ))}
+    </div>
+  );
+};
diff --git a/packages/ui/src/lib/i18n/messages/de.settings.ts b/packages/ui/src/lib/i18n/messages/de.settings.ts
index 104a37d9..635a6bfd 100644
--- a/packages/ui/src/lib/i18n/messages/de.settings.ts
+++ b/packages/ui/src/lib/i18n/messages/de.settings.ts
@@ -445,6 +445,9 @@ export const settingsDict = {
   'settings.openchamber.about.title': 'Über OpenChamber',
   'settings.openchamber.about.field.version': 'Version',
   'settings.openchamber.about.field.openCodeVersion': 'OpenCode-Version',
+  'settings.openchamber.about.field.instanceUrls': 'Instanz-URLs',
+  'settings.openchamber.about.field.applicationUrl': 'Anwendung',
+  'settings.openchamber.about.field.tunnelUrl': 'Tunnel',
   'settings.openchamber.about.state.checking': 'Wird geprüft...',
   'settings.openchamber.about.state.upToDate': 'Aktuell',
   'settings.openchamber.about.state.unknown': 'unbekannt',
diff --git a/packages/ui/src/lib/i18n/messages/en.settings.ts b/packages/ui/src/lib/i18n/messages/en.settings.ts
index c021f305..860c1fc7 100644
--- a/packages/ui/src/lib/i18n/messages/en.settings.ts
+++ b/packages/ui/src/lib/i18n/messages/en.settings.ts
@@ -464,6 +464,9 @@ export const settingsDict = {
   'settings.openchamber.about.title': 'About OpenChamber',
   'settings.openchamber.about.field.version': 'Version',
   'settings.openchamber.about.field.openCodeVersion': 'OpenCode version',
+  'settings.openchamber.about.field.instanceUrls': 'Instance URLs',
+  'settings.openchamber.about.field.applicationUrl': 'Application',
+  'settings.openchamber.about.field.tunnelUrl': 'Tunnel',
   'settings.openchamber.about.state.checking': 'Checking...',
   'settings.openchamber.about.state.upToDate': 'Up to date',
   'settings.openchamber.about.state.unknown': 'unknown',
diff --git a/packages/ui/src/lib/i18n/messages/es.settings.ts b/packages/ui/src/lib/i18n/messages/es.settings.ts
index 74db714b..db7149be 100644
--- a/packages/ui/src/lib/i18n/messages/es.settings.ts
+++ b/packages/ui/src/lib/i18n/messages/es.settings.ts
@@ -431,6 +431,9 @@ export const settingsDict = {
   "settings.openchamber.about.title": "Acerca de OpenChamber",
   "settings.openchamber.about.field.version": "Versión",
   "settings.openchamber.about.field.openCodeVersion": "Versión de OpenCode",
+  "settings.openchamber.about.field.instanceUrls": "URLs de la instancia",
+  "settings.openchamber.about.field.applicationUrl": "Aplicación",
+  "settings.openchamber.about.field.tunnelUrl": "Túnel",
   "settings.openchamber.about.state.checking": "Comprobando...",
   "settings.openchamber.about.state.upToDate": "Actualizado",
   "settings.openchamber.about.state.unknown": "desconocido",
diff --git a/packages/ui/src/lib/i18n/messages/fr.settings.ts b/packages/ui/src/lib/i18n/messages/fr.settings.ts
index f0c98448..599edb5d 100644
--- a/packages/ui/src/lib/i18n/messages/fr.settings.ts
+++ b/packages/ui/src/lib/i18n/messages/fr.settings.ts
@@ -2059,6 +2059,9 @@ export const settingsDict = {
   'settings.remoteInstances.relay.toast.offerFailed': 'Échec de la création du lien d’association',
   'settings.remoteInstances.relay.toast.linkCopied': 'Lien d’association copié',
   'settings.openchamber.about.field.openCodeVersion': 'Version d’OpenCode',
+  'settings.openchamber.about.field.instanceUrls': 'URLs de l’instance',
+  'settings.openchamber.about.field.applicationUrl': 'Application',
+  'settings.openchamber.about.field.tunnelUrl': 'Tunnel',
   'settings.openchamber.about.state.unknown': 'inconnue',
   'settings.voice.page.field.ttsInputMode': 'Mode d’entrée TTS',
   'settings.voice.page.field.ttsInputModeSanitized': 'Nettoyé',
diff --git a/packages/ui/src/lib/i18n/messages/ja.settings.ts b/packages/ui/src/lib/i18n/messages/ja.settings.ts
index 0c82f734..d585d198 100644
--- a/packages/ui/src/lib/i18n/messages/ja.settings.ts
+++ b/packages/ui/src/lib/i18n/messages/ja.settings.ts
@@ -464,6 +464,9 @@ export const settingsDict = {
   'settings.openchamber.about.title': 'OpenChamber について',
   'settings.openchamber.about.field.version': 'バージョン',
   'settings.openchamber.about.field.openCodeVersion': 'OpenCode バージョン',
+  'settings.openchamber.about.field.instanceUrls': 'インスタンスのURL',
+  'settings.openchamber.about.field.applicationUrl': 'アプリケーション',
+  'settings.openchamber.about.field.tunnelUrl': 'トンネル',
   'settings.openchamber.about.state.checking': '確認中...',
   'settings.openchamber.about.state.upToDate': '最新です',
   'settings.openchamber.about.state.unknown': '不明',
diff --git a/packages/ui/src/lib/i18n/messages/ko.settings.ts b/packages/ui/src/lib/i18n/messages/ko.settings.ts
index aa53cbfd..320b6404 100644
--- a/packages/ui/src/lib/i18n/messages/ko.settings.ts
+++ b/packages/ui/src/lib/i18n/messages/ko.settings.ts
@@ -431,6 +431,9 @@ export const settingsDict = {
   'settings.openchamber.about.title': 'OpenChamber 정보',
   'settings.openchamber.about.field.version': '버전',
   'settings.openchamber.about.field.openCodeVersion': 'OpenCode 버전',
+  'settings.openchamber.about.field.instanceUrls': '인스턴스 URL',
+  'settings.openchamber.about.field.applicationUrl': '애플리케이션',
+  'settings.openchamber.about.field.tunnelUrl': '터널',
   'settings.openchamber.about.state.checking': '확인 중...',
   'settings.openchamber.about.state.upToDate': '최신 상태',
   'settings.openchamber.about.state.unknown': '알 수 없음',
diff --git a/packages/ui/src/lib/i18n/messages/pl.settings.ts b/packages/ui/src/lib/i18n/messages/pl.settings.ts
index aa3af5d6..0d034d62 100644
--- a/packages/ui/src/lib/i18n/messages/pl.settings.ts
+++ b/packages/ui/src/lib/i18n/messages/pl.settings.ts
@@ -722,6 +722,9 @@ export const settingsDict = {
   'settings.openchamber.about.actions.updateToVersion': 'Aktualizuj do wersji {version}',
   'settings.openchamber.about.field.version': 'Wersja',
   'settings.openchamber.about.field.openCodeVersion': 'Wersja OpenCode',
+  'settings.openchamber.about.field.instanceUrls': 'Adresy URL instancji',
+  'settings.openchamber.about.field.applicationUrl': 'Aplikacja',
+  'settings.openchamber.about.field.tunnelUrl': 'Tunel',
   'settings.openchamber.about.state.checking': 'Sprawdzanie...',
   'settings.openchamber.about.state.upToDate': 'Aktualna wersja',
   'settings.openchamber.about.state.unknown': 'nieznane',
diff --git a/packages/ui/src/lib/i18n/messages/pt-BR.settings.ts b/packages/ui/src/lib/i18n/messages/pt-BR.settings.ts
index c321f233..41c6acde 100644
--- a/packages/ui/src/lib/i18n/messages/pt-BR.settings.ts
+++ b/packages/ui/src/lib/i18n/messages/pt-BR.settings.ts
@@ -431,6 +431,9 @@ export const settingsDict = {
   "settings.openchamber.about.title": "Sobre o OpenChamber",
   "settings.openchamber.about.field.version": "Versão",
   "settings.openchamber.about.field.openCodeVersion": "Versão do OpenCode",
+  "settings.openchamber.about.field.instanceUrls": "URLs da instância",
+  "settings.openchamber.about.field.applicationUrl": "Aplicativo",
+  "settings.openchamber.about.field.tunnelUrl": "Túnel",
   "settings.openchamber.about.state.checking": "Verificando...",
   "settings.openchamber.about.state.upToDate": "Atualizado",
   "settings.openchamber.about.state.unknown": "desconhecido",
diff --git a/packages/ui/src/lib/i18n/messages/uk.settings.ts b/packages/ui/src/lib/i18n/messages/uk.settings.ts
index c5afd784..8cfb24c1 100644
--- a/packages/ui/src/lib/i18n/messages/uk.settings.ts
+++ b/packages/ui/src/lib/i18n/messages/uk.settings.ts
@@ -431,6 +431,9 @@ export const settingsDict = {
   "settings.openchamber.about.title": "Про OpenChamber",
   "settings.openchamber.about.field.version": "Версія",
   "settings.openchamber.about.field.openCodeVersion": "Версія OpenCode",
+  "settings.openchamber.about.field.instanceUrls": "URL-адреси екземпляра",
+  "settings.openchamber.about.field.applicationUrl": "Застосунок",
+  "settings.openchamber.about.field.tunnelUrl": "Тунель",
   "settings.openchamber.about.state.checking": "Перевірка...",
   "settings.openchamber.about.state.upToDate": "В актуальному стані",
   "settings.openchamber.about.state.unknown": "невідомо",
diff --git a/packages/ui/src/lib/i18n/messages/zh-CN.settings.ts b/packages/ui/src/lib/i18n/messages/zh-CN.settings.ts
index 2d111132..9fea8ea9 100644
--- a/packages/ui/src/lib/i18n/messages/zh-CN.settings.ts
+++ b/packages/ui/src/lib/i18n/messages/zh-CN.settings.ts
@@ -431,6 +431,9 @@ export const settingsDict = {
   'settings.openchamber.about.title': '关于 OpenChamber',
   'settings.openchamber.about.field.version': '版本',
   'settings.openchamber.about.field.openCodeVersion': 'OpenCode 版本',
+  'settings.openchamber.about.field.instanceUrls': '实例 URL',
+  'settings.openchamber.about.field.applicationUrl': '应用',
+  'settings.openchamber.about.field.tunnelUrl': '隧道',
   'settings.openchamber.about.state.checking': '检查中...',
   'settings.openchamber.about.state.upToDate': '已是最新',
   'settings.openchamber.about.state.unknown': '未知',
diff --git a/packages/ui/src/lib/i18n/messages/zh-TW.settings.ts b/packages/ui/src/lib/i18n/messages/zh-TW.settings.ts
index 4118c83d..54a2294c 100644
--- a/packages/ui/src/lib/i18n/messages/zh-TW.settings.ts
+++ b/packages/ui/src/lib/i18n/messages/zh-TW.settings.ts
@@ -428,6 +428,9 @@
   'settings.openchamber.about.title': '關於 OpenChamber',
   'settings.openchamber.about.field.version': '版本',
   'settings.openchamber.about.field.openCodeVersion': 'OpenCode 版本',
+  'settings.openchamber.about.field.instanceUrls': '執行個體 URL',
+  'settings.openchamber.about.field.applicationUrl': '應用程式',
+  'settings.openchamber.about.field.tunnelUrl': '隧道',
   'settings.openchamber.about.state.checking': '檢查中...',
   'settings.openchamber.about.state.upToDate': '已是最新',
   'settings.openchamber.about.state.unknown': '未知',
diff --git a/packages/web/server/index.js b/packages/web/server/index.js
index 4eac3336..8086e562 100644
--- a/packages/web/server/index.js
+++ b/packages/web/server/index.js
@@ -1487,6 +1487,10 @@ async function main(options = {}) {
   // relay candidate lazily at request time, so a late-bound holder is enough.
   let relayServiceInstance = null;
 
+  // Same pattern for the tunnel runtime: created after the base routes so
+  // /api/system/info resolves port + tunnel URL lazily at request time.
+  let tunnelRuntimeContextHolder = null;
+
   const bootstrapResult = bootstrapRuntime.setupBaseRoutes(app, {
     process,
     openchamberVersion: OPENCHAMBER_VERSION,
@@ -1523,6 +1527,15 @@ async function main(options = {}) {
         apiOnly,
       };
     },
+    // Port this instance serves on and the active tunnel's public URL (if
+    // any), for /api/system/info. Resolved lazily because the tunnel runtime
+    // is created after these base routes are registered.
+    getServerPort: () => {
+      const activePort = tunnelRuntimeContextHolder?.getActivePort?.();
+      if (Number.isFinite(activePort) && activePort > 0) return activePort;
+      return Number.isFinite(port) && port > 0 ? port : null;
+    },
+    getTunnelUrl: () => tunnelRuntimeContextHolder?.tunnelService?.getPublicUrl?.() ?? null,
     verboseRequestLogs: OPENCHAMBER_VERBOSE_REQUEST_LOGS,
     uiPassword,
     tunnelAuthController,
@@ -1598,6 +1611,7 @@ async function main(options = {}) {
 
   const tunnelRuntimeContext = tunnelWiringRuntime.initialize(app, port);
   const { tunnelService, startTunnelWithNormalizedRequest } = tunnelRuntimeContext;
+  tunnelRuntimeContextHolder = tunnelRuntimeContext;
 
   // Private relay host service: config + management routes + host client
   // lifecycle. Loopback port comes from the same source the tunnel uses so
diff --git a/packages/web/server/lib/opencode/bootstrap-runtime.js b/packages/web/server/lib/opencode/bootstrap-runtime.js
index 392c42e8..f3d60a19 100644
--- a/packages/web/server/lib/opencode/bootstrap-runtime.js
+++ b/packages/web/server/lib/opencode/bootstrap-runtime.js
@@ -19,6 +19,8 @@ export const createBootstrapRuntime = (dependencies) => {
       serverStartedAt,
       gracefulShutdown,
       getHealthSnapshot,
+      getServerPort,
+      getTunnelUrl,
       verboseRequestLogs,
       uiPassword,
       tunnelAuthController,
@@ -81,6 +83,8 @@ export const createBootstrapRuntime = (dependencies) => {
       gracefulShutdown,
       getHealthSnapshot,
       getServerId,
+      getServerPort,
+      getTunnelUrl,
       tunnelAuthController,
       uiAuthController,
     });
diff --git a/packages/web/server/lib/opencode/core-routes.js b/packages/web/server/lib/opencode/core-routes.js
index afe5f9e4..87bbb05e 100644
--- a/packages/web/server/lib/opencode/core-routes.js
+++ b/packages/web/server/lib/opencode/core-routes.js
@@ -67,6 +67,12 @@ export const registerServerStatusRoutes = (app, dependencies) => {
     serverStartedAt,
     gracefulShutdown,
     getHealthSnapshot,
+    // Port this OpenChamber instance serves on and the tunnel public URL (if
+    // a tunnel is active). Exposed on /api/system/info so the UI can surface
+    // the active instance's service URLs. Optional: older wiring omits them
+    // and the endpoint reports null.
+    getServerPort = () => null,
+    getTunnelUrl = () => null,
     // Stable server identity (hash of the public signing key — not a secret).
     // Exposed on /health and /api/version so a client can verify that a
     // learned/probed address belongs to the expected server BEFORE sending its
@@ -356,6 +362,8 @@ export const registerServerStatusRoutes = (app, dependencies) => {
       runtime: runtimeName,
       pid: process.pid,
       startedAt: serverStartedAt,
+      port: getServerPort(),
+      tunnelUrl: getTunnelUrl(),
     });
   });
 
diff --git a/packages/web/server/lib/opencode/core-routes.test.js b/packages/web/server/lib/opencode/core-routes.test.js
index 200a1c13..145484cf 100644
--- a/packages/web/server/lib/opencode/core-routes.test.js
+++ b/packages/web/server/lib/opencode/core-routes.test.js
@@ -791,4 +791,46 @@ describe('client auth routes', () => {
       socket: { remoteAddress: '203.0.113.10' },
     })).toBe('unknown-public');
   });
+
+  it('reports null port and tunnel URL on /api/system/info when no getters are wired', async () => {
+    const app = express();
+    registerServerStatusRoutes(app, {
+      process,
+      serverStartedAt: '2026-01-01T00:00:00.000Z',
+      gracefulShutdown: vi.fn(async () => {}),
+      getHealthSnapshot: () => ({ status: 'ok' }),
+      openchamberVersion: '1.0.0',
+      runtimeName: 'test',
+      express,
+    });
+
+    const response = await request(app).get('/api/system/info');
+    expect(response.status).toBe(200);
+    expect(response.body.openchamberVersion).toBe('1.0.0');
+    expect(response.body.runtime).toBe('test');
+    expect(response.body.pid).toBeTypeOf('number');
+    expect(response.body.startedAt).toBeTypeOf('string');
+    expect(response.body.port).toBeNull();
+    expect(response.body.tunnelUrl).toBeNull();
+  });
+
+  it('reports the instance port and tunnel URL on /api/system/info from the wired getters', async () => {
+    const app = express();
+    registerServerStatusRoutes(app, {
+      process,
+      serverStartedAt: '2026-01-01T00:00:00.000Z',
+      gracefulShutdown: vi.fn(async () => {}),
+      getHealthSnapshot: () => ({ status: 'ok' }),
+      openchamberVersion: '1.0.0',
+      runtimeName: 'test',
+      express,
+      getServerPort: () => 9988,
+      getTunnelUrl: () => 'https://worktree-a.example.trycloudflare.com',
+    });
+
+    const response = await request(app).get('/api/system/info');
+    expect(response.status).toBe(200);
+    expect(response.body.port).toBe(9988);
+    expect(response.body.tunnelUrl).toBe('https://worktree-a.example.trycloudflare.com');
+  });
 });

From 70226149ce35037eaf44d2e7cd6d2160be41ee60 Mon Sep 17 00:00:00 2001
From: Wsyjq <2723376006@qq.com>
Date: Fri, 7 Aug 2026 05:46:21 +0800
Subject: [PATCH 49/57] fix(chat): pin existing-session sends to captured
 target (#2424)

* fix(chat): pin sends to captured session

* fix(chat): handle runtime cancellation consistently
---
 packages/ui/src/components/chat/ChatInput.tsx | 36 +++++---
 .../hooks/useQueuedMessageAutoSend.test.ts    | 14 ++-
 .../ui/src/hooks/useQueuedMessageAutoSend.ts  |  7 +-
 packages/ui/src/lib/opencode/client.test.ts   | 34 +++++++-
 packages/ui/src/lib/opencode/client.ts        | 16 ++++
 packages/ui/src/sync/DOCUMENTATION.md         |  5 +-
 packages/ui/src/sync/session-actions.test.ts  |  8 +-
 packages/ui/src/sync/session-actions.ts       | 19 +++-
 packages/ui/src/sync/session-ui-store.test.js | 87 ++++++++++++++++++-
 packages/ui/src/sync/session-ui-store.ts      | 27 +++++-
 10 files changed, 222 insertions(+), 31 deletions(-)

diff --git a/packages/ui/src/components/chat/ChatInput.tsx b/packages/ui/src/components/chat/ChatInput.tsx
index ba493f55..38871269 100644
--- a/packages/ui/src/components/chat/ChatInput.tsx
+++ b/packages/ui/src/components/chat/ChatInput.tsx
@@ -936,10 +936,18 @@ const ChatInputComponent: React.FC<ChatInputProps> = ({ onOpenSettings, scrollTo
         setPrPickerOpen(true);
     }, []);
 
+    const getSubmitErrorMessage = (error: unknown, fallback: string) => {
+        const message = error instanceof Error ? error.message : '';
+        return message.toLowerCase().includes('runtime changed')
+            ? t('chat.chatInput.toast.messageSendFailed')
+            : message || fallback;
+    };
+
     const handleSubmit = async (options?: SubmitOptions) => {
         const queuedOnly = options?.queuedOnly ?? false;
         const queuedMessageId = options?.queuedMessageId;
         const delivery = options?.delivery === 'steer' && sessionPhase !== 'idle' ? 'steer' : undefined;
+        const capturedTarget = messageQueueTarget;
         const inputSnapshot = options?.presetText != null
             ? {
                 message: options.presetText,
@@ -1012,7 +1020,9 @@ const ChatInputComponent: React.FC<ChatInputProps> = ({ onOpenSettings, scrollTo
             }
         }
 
-        const sendMessageOptions = delivery ? { delivery } : undefined;
+        const sendMessageOptions = capturedTarget
+            ? { target: capturedTarget, ...(delivery ? { delivery } : {}) }
+            : delivery ? { delivery } : undefined;
 
         // Inline review comments and synthetic context are consumed before
         // assembly so a failed send can restore exactly what it took.
@@ -1058,10 +1068,10 @@ const ChatInputComponent: React.FC<ChatInputProps> = ({ onOpenSettings, scrollTo
         if (outgoing.isEmpty) return;
 
         // Clear queue and input
-        if (messageQueueTarget && queuedMessageId) {
-            removeFromQueue(messageQueueTarget, queuedMessageId);
-        } else if (messageQueueTarget && hasQueuedMessages) {
-            clearQueue(messageQueueTarget);
+        if (capturedTarget && queuedMessageId) {
+            removeFromQueue(capturedTarget, queuedMessageId);
+        } else if (capturedTarget && hasQueuedMessages) {
+            clearQueue(capturedTarget);
         }
         if (!queuedOnly) {
             setMessage('');
@@ -1111,7 +1121,7 @@ const ChatInputComponent: React.FC<ChatInputProps> = ({ onOpenSettings, scrollTo
                     const compactDirectory = useSessionUIStore.getState().getDirectoryForSession(currentSessionId) || currentDirectory || undefined;
                     await opencodeClient.summarizeSession(currentSessionId, currentProviderId, currentModelId, compactDirectory);
                 } catch (error) {
-                    toast.error(error instanceof Error ? error.message : t('chat.chatInput.toast.compactFailed'));
+                    toast.error(getSubmitErrorMessage(error, t('chat.chatInput.toast.compactFailed')));
                 }
                 return;
             }
@@ -1143,15 +1153,13 @@ const ChatInputComponent: React.FC<ChatInputProps> = ({ onOpenSettings, scrollTo
                     );
                     scrollToBottom?.();
                 } catch (error) {
-                    toast.error(error instanceof Error ? error.message : t(command.errorToastKey));
+                    toast.error(getSubmitErrorMessage(error, t(command.errorToastKey)));
                 }
                 return;
             }
         }
 
-        const currentSessionDirectory = currentSessionId
-            ? useSessionUIStore.getState().getDirectoryForSession(currentSessionId) || currentDirectory
-            : currentDirectory;
+        const currentSessionDirectory = capturedTarget?.directory ?? currentDirectory;
         const shouldAddResponseStyle = newSessionDraftOpen || (currentSessionId ? !hasUserMessages(currentSessionId, currentSessionDirectory) : false);
         if (shouldAddResponseStyle) {
             const responseStyleInstruction = await fetchResponseStyleInstruction().catch(() => null);
@@ -1258,6 +1266,14 @@ const ChatInputComponent: React.FC<ChatInputProps> = ({ onOpenSettings, scrollTo
                 return;
             }
 
+            if (normalized.includes('runtime changed')) {
+                if (allAttachments.length > 0) {
+                    useInputStore.getState().setAttachedFiles(allAttachments);
+                }
+                toast.error(t('chat.chatInput.toast.messageSendFailed'));
+                return;
+            }
+
             if (allAttachments.length > 0) {
                 useInputStore.getState().setAttachedFiles(allAttachments);
             }
diff --git a/packages/ui/src/hooks/useQueuedMessageAutoSend.test.ts b/packages/ui/src/hooks/useQueuedMessageAutoSend.test.ts
index f5a6a343..c6438e36 100644
--- a/packages/ui/src/hooks/useQueuedMessageAutoSend.test.ts
+++ b/packages/ui/src/hooks/useQueuedMessageAutoSend.test.ts
@@ -272,7 +272,11 @@ describe('buildQueuedAutoSendPayload', () => {
     ]);
 
     expect(payload).not.toBeNull();
-    await sendQueuedAutoSendPayload('session-original', '/repo', payload!, {
+    await sendQueuedAutoSendPayload({
+      runtimeKey: 'runtime-original',
+      sessionId: 'session-original',
+      directory: '/repo',
+    }, payload!, {
       providerID: 'provider-1',
       modelID: 'model-1',
       agent: 'agent-1',
@@ -290,7 +294,13 @@ describe('buildQueuedAutoSendPayload', () => {
       undefined,
       'variant-1',
       'normal',
-      { sessionId: 'session-original', directory: '/repo' },
+      {
+        target: {
+          runtimeKey: 'runtime-original',
+          sessionId: 'session-original',
+          directory: '/repo',
+        },
+      },
     ]);
   });
 });
diff --git a/packages/ui/src/hooks/useQueuedMessageAutoSend.ts b/packages/ui/src/hooks/useQueuedMessageAutoSend.ts
index 38e95713..87bee797 100644
--- a/packages/ui/src/hooks/useQueuedMessageAutoSend.ts
+++ b/packages/ui/src/hooks/useQueuedMessageAutoSend.ts
@@ -103,8 +103,7 @@ type ResolvedQueuedSendConfig = {
 };
 
 export const sendQueuedAutoSendPayload = (
-  sessionId: string,
-  directory: string,
+  target: MessageQueueTarget,
   payload: QueuedAutoSendPayload,
   resolved: ResolvedQueuedSendConfig,
 ) => {
@@ -118,7 +117,7 @@ export const sendQueuedAutoSendPayload = (
     undefined,
     resolved.variant,
     'normal',
-    { sessionId, directory },
+    { target },
   );
 };
 
@@ -295,7 +294,7 @@ export function useQueuedMessageAutoSend(enabledOrOptions?: boolean | { enabled?
       useMessageQueueStore.getState().markSending(target, payload.queuedMessageId);
 
       try {
-        await sendQueuedAutoSendPayload(sessionId, target.directory, payload, {
+        await sendQueuedAutoSendPayload(target, payload, {
           providerID: resolved.providerID,
           modelID: resolved.modelID,
           agent: resolved.agent,
diff --git a/packages/ui/src/lib/opencode/client.test.ts b/packages/ui/src/lib/opencode/client.test.ts
index 4bd0d712..a691a79d 100644
--- a/packages/ui/src/lib/opencode/client.test.ts
+++ b/packages/ui/src/lib/opencode/client.test.ts
@@ -6,6 +6,7 @@ type ConfigResponse = { data: Record<string, unknown> };
 
 const configResolvers: Array<(response: ConfigResponse) => void> = [];
 let configCalls = 0;
+let runtimeKey = 'test-runtime';
 const promptAsyncCalls: unknown[][] = [];
 const promptAsyncResults: Array<unknown> = [];
 
@@ -44,7 +45,7 @@ mock.module('@/lib/runtime-url', () => ({
 
 mock.module('@/lib/runtime-switch', () => ({
   getRuntimeApiBaseUrl: mock(() => ''),
-  getRuntimeKey: mock(() => 'test-runtime'),
+  getRuntimeKey: mock(() => runtimeKey),
 }));
 
 mock.module('@/lib/runtime-fetch', () => ({
@@ -60,6 +61,7 @@ mock.module('@/lib/startupTrace', () => ({
 const { opencodeClient } = await import(`./client?cache-test=${Date.now()}`);
 
 beforeEach(() => {
+  runtimeKey = 'test-runtime';
   promptAsyncCalls.length = 0;
   promptAsyncResults.length = 0;
 });
@@ -160,4 +162,34 @@ describe('opencodeClient prompt retry behavior', () => {
     expect(promptAsyncCalls.length).toBe(1);
     expect(error instanceof Error ? error.message : String(error)).toContain('Failed to send message (503)');
   });
+
+  test('does not dispatch after the runtime changes while preparing attachments', async () => {
+    runtimeKey = 'runtime-a';
+    const pending = opencodeClient.sendMessage({
+      id: 'ses_runtime_race',
+      providerID: 'runtime-race-provider',
+      modelID: 'model-a',
+      text: 'hello',
+      runtimeKey: 'runtime-a',
+      files: [{
+        type: 'file',
+        mime: 'text/markdown',
+        filename: 'notes.md',
+        url: 'data:text/markdown,hello',
+      }],
+    });
+
+    runtimeKey = 'runtime-b';
+
+    let error: unknown = null;
+    try {
+      await pending;
+    } catch (caught) {
+      error = caught;
+    }
+
+    expect(error).toBeInstanceOf(Error);
+    expect(error instanceof Error ? error.message : String(error)).toContain('runtime changed');
+    expect(promptAsyncCalls).toHaveLength(0);
+  });
 });
diff --git a/packages/ui/src/lib/opencode/client.ts b/packages/ui/src/lib/opencode/client.ts
index 7b618f4a..7697b8a0 100644
--- a/packages/ui/src/lib/opencode/client.ts
+++ b/packages/ui/src/lib/opencode/client.ts
@@ -269,6 +269,12 @@ class OpencodeService {
     this.client = createRuntimeOpencodeClient({ baseUrl: this.baseUrl });
   }
 
+  private assertRuntimeUnchanged(runtimeKey?: string): void {
+    if (runtimeKey && runtimeKey !== getRuntimeKey()) {
+      throw new Error('Message was not sent because the runtime changed.');
+    }
+  }
+
   getBaseUrl(): string {
     return this.baseUrl;
   }
@@ -744,6 +750,7 @@ class OpencodeService {
   }
 
   async sendMessage(params: {
+    runtimeKey?: string;
     id: string;
     providerID: string;
     modelID: string;
@@ -769,6 +776,8 @@ class OpencodeService {
     };
     directory?: string | null;
   }): Promise<string> {
+    this.assertRuntimeUnchanged(params.runtimeKey);
+
     // Use the optimistic/client-generated ID as the real user message ID so SSE
     // can reconcile the echoed server message in-place.
     const messageId = params.messageId ?? ascendingId("msg");
@@ -852,6 +861,7 @@ class OpencodeService {
     }
 
     assertProviderCircuitClosed(params.providerID);
+    this.assertRuntimeUnchanged(params.runtimeKey);
 
     let response: Response;
 
@@ -918,6 +928,7 @@ class OpencodeService {
   }
 
   async sendCommand(params: {
+    runtimeKey?: string;
     id: string;
     providerID: string;
     modelID: string;
@@ -929,6 +940,8 @@ class OpencodeService {
     messageId?: string;
     directory?: string | null;
   }): Promise<string> {
+    this.assertRuntimeUnchanged(params.runtimeKey);
+
     const tempMessageId = params.messageId ?? ascendingId("msg");
 
     const parts: FilePartInput[] = [];
@@ -939,6 +952,7 @@ class OpencodeService {
     }
 
     const requestDirectory = this.normalizeCandidatePath(params.directory ?? null) ?? this.currentDirectory;
+    this.assertRuntimeUnchanged(params.runtimeKey);
 
     const response = await this.client.session.command({
       sessionID: params.id,
@@ -968,6 +982,7 @@ class OpencodeService {
   }
 
   async shellSession(params: {
+    runtimeKey?: string;
     sessionId: string;
     command: string;
     agent: string;
@@ -975,6 +990,7 @@ class OpencodeService {
     messageId?: string;
     directory?: string | null;
   }): Promise<{ info: Message; parts: Part[] }> {
+    this.assertRuntimeUnchanged(params.runtimeKey);
     const requestDirectory = this.normalizeCandidatePath(params.directory ?? null) ?? this.currentDirectory;
     const response = await this.client.session.shell({
       sessionID: params.sessionId,
diff --git a/packages/ui/src/sync/DOCUMENTATION.md b/packages/ui/src/sync/DOCUMENTATION.md
index 50202a71..e379a4e5 100644
--- a/packages/ui/src/sync/DOCUMENTATION.md
+++ b/packages/ui/src/sync/DOCUMENTATION.md
@@ -244,8 +244,9 @@ Rules:
 2. If an action targets a session by ID, resolve the **session's own directory**. Do not assume the current directory is correct.
 3. `session-ui-store.ts` should delegate to `session-actions.ts` for these mutations instead of duplicating SDK calls.
 4. Sending after a revert commits the new branch optimistically: remove the reverted tail and marker before inserting the new message, and restore both if the send is rejected.
-5. After session creation, the directory returned by the server is authoritative over the requested draft directory. The server may canonicalize a worktree path, and the first prompt must use the same directory identity as the created session.
-6. A prompt send that fails **after** the request left the client is ambiguous, never a definite failure: the server may already be answering it. Transports tag those errors (`markAmbiguousTransportFailure` in `@/lib/relay/transport-error`; the relay tunnel tags every stream that dies with a request in flight), and `isAmbiguousSendFailure` reads the tag before falling back to status/text heuristics. An ambiguous failure waits for the connection to return, refetches recent messages, and confirms the optimistic message in place instead of rolling it back — rolling it back lets the message queue re-send a prompt the engine is already running, producing two independent AI responses for one user message.
+5. Composer and queued sends carry their captured runtime, directory, and session through asynchronous preparation. A runtime change cancels the send instead of re-resolving it against the new runtime.
+6. After session creation, the directory returned by the server is authoritative over the requested draft directory. The server may canonicalize a worktree path, and the first prompt must use the same directory identity as the created session.
+7. A prompt send that fails **after** the request left the client is ambiguous, never a definite failure: the server may already be answering it. Transports tag those errors (`markAmbiguousTransportFailure` in `@/lib/relay/transport-error`; the relay tunnel tags every stream that dies with a request in flight), and `isAmbiguousSendFailure` reads the tag before falling back to status/text heuristics. An ambiguous failure waits for the connection to return, refetches recent messages, and confirms the optimistic message in place instead of rolling it back — rolling it back lets the message queue re-send a prompt the engine is already running, producing two independent AI responses for one user message.
 
 Examples of global-store updates performed in `session-actions.ts`:
 
diff --git a/packages/ui/src/sync/session-actions.test.ts b/packages/ui/src/sync/session-actions.test.ts
index d815b6dd..4c96b473 100644
--- a/packages/ui/src/sync/session-actions.test.ts
+++ b/packages/ui/src/sync/session-actions.test.ts
@@ -1027,7 +1027,7 @@ describe("optimisticSend target directory", () => {
     expect(targetStore.getState().part.msg_2).toEqual([revertedPart])
   })
 
-  test("allows callers to block final send when runtime changes after optimistic insert", async () => {
+  test("rolls back a captured send when the runtime changes after optimistic insert", async () => {
     const targetStore = createStore({})
     const childStores = createChildStores([["/target/project", targetStore]])
     let optimisticAdd: OptimisticAddCall | null = null
@@ -1052,15 +1052,15 @@ describe("optimisticSend target directory", () => {
       await optimisticSend({
         sessionId: "session-race",
         directory: "/target/project",
+        runtimeKey: "runtime-a",
         content: "hello",
         providerID: "provider",
         modelID: "model",
-        beforeOptimisticInsert: () => {
+        onOptimisticInsert: () => {
           expect(getRuntimeKey()).toBe("runtime-a")
+          switchRuntimeEndpoint({ apiBaseUrl: "http://runtime-b.test", runtimeKey: "runtime-b" })
         },
         send: async () => {
-          switchRuntimeEndpoint({ apiBaseUrl: "http://runtime-b.test", runtimeKey: "runtime-b" })
-          if (getRuntimeKey() !== "runtime-a") throw new Error("Auto-review stopped because the runtime changed.")
           finalSendCalled = true
         },
       })
diff --git a/packages/ui/src/sync/session-actions.ts b/packages/ui/src/sync/session-actions.ts
index aa8cdb10..23f1f943 100644
--- a/packages/ui/src/sync/session-actions.ts
+++ b/packages/ui/src/sync/session-actions.ts
@@ -1257,6 +1257,7 @@ function ascendingId(prefix: string): string {
  * handles deduplication when the server echoes back the real message.
  */
 export async function optimisticSend(input: {
+  runtimeKey?: string
   sessionId: string
   content: string
   providerID: string
@@ -1273,9 +1274,20 @@ export async function optimisticSend(input: {
   if (!_optimisticAdd || !_optimisticRemove) {
     throw new Error("Optimistic refs not set — is useSync() mounted?")
   }
+  const optimisticAdd = _optimisticAdd
+  const optimisticRemove = _optimisticRemove
+  const optimisticConfirm = _optimisticConfirm
 
+  const assertRuntimeUnchanged = () => {
+    if (input.runtimeKey && input.runtimeKey !== getRuntimeKey()) {
+      throw new Error("Message was not sent because the runtime changed.")
+    }
+  }
+
+  assertRuntimeUnchanged()
   await waitForConnectionOrThrow()
   input.beforeOptimisticInsert?.()
+  assertRuntimeUnchanged()
 
   const targetDirectory = input.directory ?? dir()
   const store = targetDirectory ? dirStoreForDirectory(targetDirectory) : dirStore()
@@ -1341,7 +1353,7 @@ export async function optimisticSend(input: {
   } as unknown as Message
 
   // Insert into store + register in shadow Map (for mergeOptimisticPage cleanup)
-  _optimisticAdd({
+  optimisticAdd({
     sessionID: input.sessionId,
     directory: targetDirectory,
     message: optimisticMessage,
@@ -1359,6 +1371,7 @@ export async function optimisticSend(input: {
   })
 
   try {
+    assertRuntimeUnchanged()
     await input.send(messageID)
   } catch (error) {
     const status = getErrorStatus(error)
@@ -1369,7 +1382,7 @@ export async function optimisticSend(input: {
 
     if (acceptedRecords) {
       materializeConfirmedSendRecords(store, input.sessionId, messageID, acceptedRecords)
-      _optimisticConfirm?.({
+      optimisticConfirm?.({
         sessionID: input.sessionId,
         directory: targetDirectory,
         messageID,
@@ -1396,7 +1409,7 @@ export async function optimisticSend(input: {
     console.warn("[session-actions] prompt send rejected; rolling back optimistic message", failureRecord)
 
     // Rollback via optimistic infrastructure
-    _optimisticRemove({
+    optimisticRemove({
       sessionID: input.sessionId,
       directory: targetDirectory,
       messageID,
diff --git a/packages/ui/src/sync/session-ui-store.test.js b/packages/ui/src/sync/session-ui-store.test.js
index ce4cf88f..cd7dcdd1 100644
--- a/packages/ui/src/sync/session-ui-store.test.js
+++ b/packages/ui/src/sync/session-ui-store.test.js
@@ -8,6 +8,7 @@ import { setActionRefs, setOptimisticRefs } from './session-actions';
 import { useSkillsStore } from '@/stores/useSkillsStore';
 import { useCommandsStore } from '@/stores/useCommandsStore';
 import { useConfigStore } from '@/stores/useConfigStore';
+import { getRuntimeKey } from '@/lib/runtime-switch';
 
 /**
  * Unit tests for session worktree routing through the authoritative store.
@@ -228,6 +229,85 @@ describe('routeMessage directory scoping', () => {
   });
 });
 
+describe('sendMessage captured target', () => {
+  let originalSendMessage;
+  const calls = [];
+
+  beforeEach(() => {
+    calls.length = 0;
+    const childStore = {
+      getState: () => ({ session: [], message: {}, part: {}, session_status: {} }),
+      setState: () => {},
+    };
+    const childStores = {
+      children: new Map(),
+      ensureChild: () => childStore,
+      getChild: () => childStore,
+    };
+    setActionRefs(opencodeClient, childStores, () => '/current/project');
+    setOptimisticRefs(() => {}, () => {});
+    useConfigStore.setState({ isConnected: true });
+    useSessionUIStore.setState({
+      currentSessionId: 'session-current',
+      currentSessionDirectory: '/current/project',
+      newSessionDraft: { open: false, directoryOverride: null, parentID: null },
+    });
+
+    originalSendMessage = opencodeClient.sendMessage;
+    opencodeClient.sendMessage = async (params) => {
+      calls.push(params);
+      return 'msg';
+    };
+  });
+
+  afterEach(() => {
+    opencodeClient.sendMessage = originalSendMessage;
+  });
+
+  const sendToTarget = (target) => useSessionUIStore.getState().sendMessage(
+    'queued message',
+    'provider-a',
+    'model-a',
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    'normal',
+    { target },
+  );
+
+  test('uses the target captured before the active session changes', async () => {
+    await sendToTarget({
+      runtimeKey: getRuntimeKey(),
+      sessionId: 'session-captured',
+      directory: '/captured/project',
+    });
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0].runtimeKey).toBe(getRuntimeKey());
+    expect(calls[0].id).toBe('session-captured');
+    expect(calls[0].directory).toBe('/captured/project');
+  });
+
+  test('does not send a captured target through a different runtime', async () => {
+    let error = null;
+    try {
+      await sendToTarget({
+        runtimeKey: `${getRuntimeKey()}-stale`,
+        sessionId: 'session-captured',
+        directory: '/captured/project',
+      });
+    } catch (caught) {
+      error = caught;
+    }
+
+    expect(error).toBeInstanceOf(Error);
+    expect(error.message).toContain('runtime changed');
+    expect(calls).toHaveLength(0);
+  });
+});
+
 describe('slash-command goal objectives', () => {
   test('expands every $ARGUMENTS reference from the authoritative command template', () => {
     expect(expandSlashCommandGoalObjective('/issue--to-pr LIN-123 --draft', [{
@@ -370,7 +450,12 @@ describe('routeMessage skill invocation', () => {
 
     // Minimal optimistic + connection machinery so routeMessage can dispatch.
     const childStore = {
-      getState: () => ({ session_status: {} }),
+      getState: () => ({
+        session: [],
+        message: {},
+        part: {},
+        session_status: {},
+      }),
       setState: () => {},
     };
     const childStores = {
diff --git a/packages/ui/src/sync/session-ui-store.ts b/packages/ui/src/sync/session-ui-store.ts
index 4ecdb87d..429dcb4f 100644
--- a/packages/ui/src/sync/session-ui-store.ts
+++ b/packages/ui/src/sync/session-ui-store.ts
@@ -122,6 +122,7 @@ export function expandSlashCommandGoalObjective(content: string, commands: GoalC
 // ---------------------------------------------------------------------------
 
 export function routeMessage(params: {
+  runtimeKey?: string
   sessionId: string
   directory?: string | null
   content: string
@@ -138,6 +139,7 @@ export function routeMessage(params: {
   const requestDirectory = params.directory ?? undefined
   if (params.inputMode === "shell") {
     return opencodeClient.shellSession({
+      runtimeKey: params.runtimeKey,
       sessionId: params.sessionId,
       directory: requestDirectory,
       agent: params.agent ?? "",
@@ -166,6 +168,7 @@ export function routeMessage(params: {
 
     if (isCommand) {
       return optimisticSend({
+        runtimeKey: params.runtimeKey,
         sessionId: params.sessionId,
         content: params.content,
         providerID: params.providerID,
@@ -174,6 +177,7 @@ export function routeMessage(params: {
         directory: requestDirectory,
         files: params.files,
         send: (messageID) => opencodeClient.sendCommand({
+          runtimeKey: params.runtimeKey,
           id: params.sessionId,
           providerID: params.providerID,
           modelID: params.modelID,
@@ -191,6 +195,7 @@ export function routeMessage(params: {
 
   // Normal prompt — optimistic insert so message appears instantly
   return optimisticSend({
+    runtimeKey: params.runtimeKey,
     sessionId: params.sessionId,
     content: params.content,
     providerID: params.providerID,
@@ -199,6 +204,7 @@ export function routeMessage(params: {
     directory: requestDirectory,
     files: params.files,
     send: (messageID) => opencodeClient.sendMessage({
+      runtimeKey: params.runtimeKey,
       id: params.sessionId,
       providerID: params.providerID,
       modelID: params.modelID,
@@ -215,7 +221,14 @@ export function routeMessage(params: {
   })
 }
 
+type CapturedSendTarget = {
+  runtimeKey: string
+  sessionId: string
+  directory: string
+}
+
 type SendMessageOptions = {
+  target?: CapturedSendTarget
   sessionId?: string
   directory?: string
   delivery?: 'steer'
@@ -1198,8 +1211,13 @@ export const useSessionUIStore = create<SessionUIState>()((set, get) => ({
     inputMode?: "normal" | "shell",
     options?: SendMessageOptions,
   ) => {
+    const capturedTarget = options?.target
+    if (capturedTarget && capturedTarget.runtimeKey !== getRuntimeKey()) {
+      throw new Error("Message was not sent because the runtime changed.")
+    }
+
     // Clear non-Git changed-files bar on new user message for current session
-    const sid = options?.sessionId ?? get().currentSessionId;
+    const sid = capturedTarget?.sessionId ?? options?.sessionId ?? get().currentSessionId;
     if (sid) {
       const map = new Map(get().pendingChangesBarDismissed);
       map.delete(sid);
@@ -1258,7 +1276,7 @@ export const useSessionUIStore = create<SessionUIState>()((set, get) => ({
     }
 
     // ---- New session from draft ----
-    if (!options?.sessionId && draft?.open) {
+    if (!capturedTarget && !options?.sessionId && draft?.open) {
       const createdDraftSession = await materializeOpenDraftSession({
         providerID,
         modelID,
@@ -1310,7 +1328,7 @@ export const useSessionUIStore = create<SessionUIState>()((set, get) => ({
     }
 
     // ---- Existing session ----
-    const targetSessionId = options?.sessionId ?? get().currentSessionId
+    const targetSessionId = capturedTarget?.sessionId ?? options?.sessionId ?? get().currentSessionId
     const sessionAgentSelection = targetSessionId
       ? useSelectionStore.getState().getSessionAgentSelection(targetSessionId)
       : null
@@ -1345,7 +1363,7 @@ export const useSessionUIStore = create<SessionUIState>()((set, get) => ({
     }
 
     const currentSessionDirectory = targetSessionId
-      ? normalizePath(options?.directory ?? get().getDirectoryForSession(targetSessionId))
+      ? normalizePath(capturedTarget?.directory ?? options?.directory ?? get().getDirectoryForSession(targetSessionId))
       : null
     if (targetSessionId) {
       notifyMessageSent(targetSessionId)
@@ -1366,6 +1384,7 @@ export const useSessionUIStore = create<SessionUIState>()((set, get) => ({
       await applyArmedGoal(targetSessionId, currentSessionDirectory)
     }
     await routeMessage({
+      runtimeKey: capturedTarget?.runtimeKey,
       sessionId: targetSessionId || "",
       directory: currentSessionDirectory,
       content,

From 25780c92035c9fb2e2641ee04b544fc4f7ba9941 Mon Sep 17 00:00:00 2001
From: Bruno Fantauzzi <bftzia@gmail.com>
Date: Thu, 6 Aug 2026 18:55:28 -0300
Subject: [PATCH 50/57] fix(git): run post-checkout hook after worktree
 creation bootstrap (#2721)

Worktrees are created with `git worktree add --no-checkout` and populated
with `git reset --hard`, neither of which runs git's post-checkout hook.
Invoke the hook explicitly after population with git's standard arguments
(null ref previous HEAD, checked-out HEAD, flag 1) and the worktree as cwd,
mirroring `git worktree add` without --no-checkout.

A missing or non-executable hook is skipped (matching git) and a failing
hook is logged as a warning, never failing worktree creation or session
bootstrap. Applied to both the web server git service and the VS Code
runtime's git service.
---
 packages/vscode/src/gitService.ts            |  58 ++++++++
 packages/web/server/lib/git/DOCUMENTATION.md |   3 +-
 packages/web/server/lib/git/service.js       |  58 ++++++++
 packages/web/server/lib/git/service.test.js  | 148 +++++++++++++++++++
 4 files changed, 266 insertions(+), 1 deletion(-)

diff --git a/packages/vscode/src/gitService.ts b/packages/vscode/src/gitService.ts
index 35f24347..7f2a67d6 100644
--- a/packages/vscode/src/gitService.ts
+++ b/packages/vscode/src/gitService.ts
@@ -33,6 +33,7 @@ const WORKTREE_PHASE_GIT_READY = 'git-ready' as const;
 const WORKTREE_PHASE_SETUP_READY = 'setup-ready' as const;
 const WORKTREE_INDEX_LOCK_RETRY_DELAY_MS = 250;
 const WORKTREE_INDEX_LOCK_STALE_DELAY_MS = 750;
+const GIT_NULL_REF = '0'.repeat(40);
 
 const toBootstrapStateKey = (directory: string): string => {
   const normalized = normalizeDirectoryPath(directory);
@@ -1154,6 +1155,62 @@ const populateWorktreeWithLockRecovery = async (directory: string): Promise<void
   await runGitCommandOrThrow(directory, ['reset', '--hard'], 'Failed to populate worktree');
 };
 
+// Worktrees are created with `git worktree add --no-checkout` and populated
+// with `git reset --hard`, neither of which runs git's post-checkout hook —
+// git only runs it for checkouts, clone, and worktree add *without*
+// --no-checkout. Invoke the hook explicitly after population to restore git's
+// checkout semantics: git passes the previous HEAD (null ref for a brand-new
+// worktree), the new HEAD, and flag 1 for a branch checkout, and runs the hook
+// from the worktree top-level.
+const runPostCheckoutHook = async (directory: string): Promise<void> => {
+  let hookDirectory: string | null = null;
+  try {
+    const result = await runGitCommand(directory, ['rev-parse', '--git-path', 'hooks']);
+    if (!result.success) return;
+    hookDirectory = normalizeDirectoryPath(String(result.stdout || '').trim());
+  } catch {
+    return;
+  }
+  if (!hookDirectory) return;
+
+  const hookPath = path.join(hookDirectory, 'post-checkout');
+  try {
+    const stat = await fs.promises.stat(hookPath);
+    if (!stat.isFile()) return;
+    if (process.platform !== 'win32') {
+      await fs.promises.access(hookPath, fs.constants.X_OK);
+    }
+  } catch {
+    // Missing or non-executable hooks are skipped, matching git.
+    return;
+  }
+
+  const [headResult, gitDirResult] = await Promise.all([
+    runGitCommand(directory, ['rev-parse', 'HEAD']),
+    runGitCommand(directory, ['rev-parse', '--absolute-git-dir']),
+  ]);
+  if (!headResult.success || !gitDirResult.success) return;
+  const head = String(headResult.stdout || '').trim();
+  const gitDir = String(gitDirResult.stdout || '').trim();
+  if (!head || !gitDir) return;
+
+  try {
+    await execFileAsync(hookPath, [GIT_NULL_REF, head, '1'], {
+      cwd: directory,
+      env: {
+        ...(await buildGitEnv()),
+        GIT_DIR: gitDir,
+        GIT_WORK_TREE: path.resolve(directory),
+      },
+      windowsHide: true,
+    });
+  } catch (error) {
+    // A failing hook must not fail worktree creation or session bootstrap:
+    // warn and continue.
+    console.warn('[GitService] post-checkout hook failed in worktree:', error instanceof Error ? error.message : String(error));
+  }
+};
+
 const ensureOpenCodeProjectId = async (primaryWorktree: string): Promise<string> => {
   const gitDir = path.join(primaryWorktree, '.git');
   const idFile = path.join(gitDir, 'opencode');
@@ -1478,6 +1535,7 @@ const queueWorktreeBootstrap = (args: {
   const task = new Promise<void>((resolve) => setTimeout(resolve, 0))
     .then(async () => {
       await populateWorktreeWithLockRecovery(directory);
+      await runPostCheckoutHook(directory);
       if (setUpstream) {
         await applyUpstreamConfiguration({
           primaryWorktree,
diff --git a/packages/web/server/lib/git/DOCUMENTATION.md b/packages/web/server/lib/git/DOCUMENTATION.md
index 98368370..ec45bc5d 100644
--- a/packages/web/server/lib/git/DOCUMENTATION.md
+++ b/packages/web/server/lib/git/DOCUMENTATION.md
@@ -48,7 +48,7 @@ The following functions are exported and used by the web server:
 ### Worktree Operations
 - `getWorktrees(directory)`: List all git worktrees for a repository.
 - `validateWorktreeCreate(directory, input)`: Validate worktree creation parameters (mode, branchName, startRef, upstream config).
-- `createWorktree(directory, input)`: Create a new worktree (supports 'new' and 'existing' modes, upstream setup).
+- `createWorktree(directory, input)`: Create a new worktree (supports 'new' and 'existing' modes, upstream setup). After populating the worktree, the repository's `post-checkout` hook runs once with git's standard arguments (null ref as previous HEAD, the checked-out HEAD, and flag `1`) from the worktree directory, mirroring `git worktree add` without `--no-checkout`; a missing or non-executable hook is skipped and a failing hook is logged as a warning, never failing worktree creation or the session bootstrap.
 - `removeWorktree(directory, input)`: Remove a worktree (optionally delete local branch).
 - `isLinkedWorktree(directory)`: Check if directory is a linked worktree (not primary).
 
@@ -95,6 +95,7 @@ The following functions are internal helpers used by exported functions:
 - `resolveCandidateDirectory(...)`: Generate unique worktree directory candidates.
 - `resolveBranchForExistingMode(...)`: Resolve branch for existing-mode worktree creation.
 - `applyUpstreamConfiguration(...)`: Set upstream tracking for new branches.
+- `runPostCheckoutHook(directory)`: Invoke the worktree's `post-checkout` hook after population, because `git worktree add --no-checkout` and the bootstrap's `git reset --hard` never run git hooks. Runs with git's standard arguments and the worktree as cwd; skips missing/non-executable hooks and never throws on hook failure.
 - And various other internal helpers for Git command execution and parsing.
 
 ## Response Contracts
diff --git a/packages/web/server/lib/git/service.js b/packages/web/server/lib/git/service.js
index d058dd91..bd790acb 100644
--- a/packages/web/server/lib/git/service.js
+++ b/packages/web/server/lib/git/service.js
@@ -25,6 +25,7 @@ const WORKTREE_BOOTSTRAP_FAILED = 'failed';
 const WORKTREE_BOOTSTRAP_PHASE_DIRECTORY_CREATED = 'directory-created';
 const WORKTREE_BOOTSTRAP_PHASE_GIT_READY = 'git-ready';
 const WORKTREE_BOOTSTRAP_PHASE_SETUP_READY = 'setup-ready';
+const GIT_NULL_REF = '0'.repeat(40);
 const WORKTREE_INDEX_LOCK_RETRY_DELAY_MS = 250;
 const WORKTREE_INDEX_LOCK_STALE_DELAY_MS = 750;
 
@@ -1028,6 +1029,62 @@ export const populateWorktreeWithLockRecovery = async (directory) => {
   await runGitCommandOrThrow(directory, ['reset', '--hard'], 'Failed to populate worktree');
 };
 
+// Worktrees are created with `git worktree add --no-checkout` and populated
+// with `git reset --hard`, neither of which runs git's post-checkout hook —
+// git only runs it for checkouts, clone, and worktree add *without*
+// --no-checkout. Invoke the hook explicitly after population to restore git's
+// checkout semantics: git passes the previous HEAD (null ref for a brand-new
+// worktree), the new HEAD, and flag 1 for a branch checkout, and runs the hook
+// from the worktree top-level.
+const runPostCheckoutHook = async (directory) => {
+  let hookDirectory = null;
+  try {
+    const result = await runGitCommand(directory, ['rev-parse', '--git-path', 'hooks']);
+    if (!result.success) return;
+    hookDirectory = normalizeDirectoryPath(String(result.stdout || '').trim());
+  } catch {
+    return;
+  }
+  if (!hookDirectory) return;
+
+  const hookPath = path.join(hookDirectory, 'post-checkout');
+  try {
+    const stat = await fsp.stat(hookPath);
+    if (!stat.isFile()) return;
+    if (process.platform !== 'win32') {
+      await fsp.access(hookPath, fs.constants.X_OK);
+    }
+  } catch {
+    // Missing or non-executable hooks are skipped, matching git.
+    return;
+  }
+
+  const [headResult, gitDirResult] = await Promise.all([
+    runGitCommand(directory, ['rev-parse', 'HEAD']),
+    runGitCommand(directory, ['rev-parse', '--absolute-git-dir']),
+  ]);
+  if (!headResult.success || !gitDirResult.success) return;
+  const head = String(headResult.stdout || '').trim();
+  const gitDir = String(gitDirResult.stdout || '').trim();
+  if (!head || !gitDir) return;
+
+  try {
+    await execFileAsync(hookPath, [GIT_NULL_REF, head, '1'], {
+      cwd: directory,
+      env: {
+        ...(await buildGitEnv()),
+        GIT_DIR: gitDir,
+        GIT_WORK_TREE: path.resolve(directory),
+      },
+      windowsHide: true,
+    });
+  } catch (error) {
+    // A failing hook must not fail worktree creation or session bootstrap:
+    // warn and continue.
+    console.warn(`[GitService] post-checkout hook failed in worktree ${directory}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+};
+
 const derivePrimaryWorktreeRootFromGitDir = (gitDir) => {
   const normalized = normalizePath(gitDir);
   if (!normalized) return null;
@@ -1719,6 +1776,7 @@ const queueWorktreeBootstrap = (args) => {
   const task = new Promise((resolve) => setTimeout(resolve, 0))
     .then(async () => {
       await populateWorktreeWithLockRecovery(directory);
+      await runPostCheckoutHook(directory);
       if (setUpstream) {
         await applyUpstreamConfiguration({
           primaryWorktree,
diff --git a/packages/web/server/lib/git/service.test.js b/packages/web/server/lib/git/service.test.js
index 7b06d022..3127fe92 100644
--- a/packages/web/server/lib/git/service.test.js
+++ b/packages/web/server/lib/git/service.test.js
@@ -537,6 +537,154 @@ describe('createWorktree', () => {
     }
   });
 
+  const installPostCheckoutHook = (repo, script, executable = true) => {
+    const hookPath = path.join(repo, '.git', 'hooks', 'post-checkout');
+    fs.writeFileSync(hookPath, script);
+    if (executable) {
+      fs.chmodSync(hookPath, 0o755);
+    }
+    return hookPath;
+  };
+
+  it('runs the post-checkout hook after populating a created worktree', async () => {
+    if (!canRunGit()) return;
+
+    const previousXdgDataHome = process.env.XDG_DATA_HOME;
+    const dataHome = createTempDir();
+    process.env.XDG_DATA_HOME = dataHome;
+
+    try {
+      const repo = createTempDir();
+      runGit(repo, ['init', '-b', 'main']);
+      runGit(repo, ['config', 'user.email', 'test@example.com']);
+      runGit(repo, ['config', 'user.name', 'Test User']);
+      fs.writeFileSync(path.join(repo, 'README.md'), '# Test\n');
+      runGit(repo, ['add', 'README.md']);
+      runGit(repo, ['commit', '-m', 'Initial commit']);
+      const head = runGit(repo, ['rev-parse', 'HEAD']).trim();
+
+      const hookLog = path.join(dataHome, 'post-checkout.log');
+      installPostCheckoutHook(
+        repo,
+        `#!/bin/sh\nprintf '%s|%s|%s|%s' "$1" "$2" "$3" "$(pwd -P)" > ${JSON.stringify(hookLog)}\n`,
+      );
+
+      const created = await createWorktree(repo, {
+        mode: 'new',
+        worktreeName: 'hook-test',
+        branchName: 'openchamber/hook-test',
+        returnAfterDirectoryCreated: true,
+      });
+
+      await expect.poll(() => {
+        try {
+          return fs.readFileSync(hookLog, 'utf8');
+        } catch {
+          return '';
+        }
+      }, { timeout: 5_000 }).not.toBe('');
+
+      const [previousHead, newHead, flag, cwd] = fs.readFileSync(hookLog, 'utf8').split('|');
+      expect(previousHead).toBe('0000000000000000000000000000000000000000');
+      expect(newHead).toBe(head);
+      expect(flag).toBe('1');
+      expect(cwd).toBe(fs.realpathSync(created.path));
+    } finally {
+      if (previousXdgDataHome === undefined) {
+        delete process.env.XDG_DATA_HOME;
+      } else {
+        process.env.XDG_DATA_HOME = previousXdgDataHome;
+      }
+    }
+  });
+
+  it('skips a non-executable post-checkout hook', async () => {
+    if (!canRunGit()) return;
+
+    const previousXdgDataHome = process.env.XDG_DATA_HOME;
+    const dataHome = createTempDir();
+    process.env.XDG_DATA_HOME = dataHome;
+
+    try {
+      const repo = createTempDir();
+      runGit(repo, ['init', '-b', 'main']);
+      runGit(repo, ['config', 'user.email', 'test@example.com']);
+      runGit(repo, ['config', 'user.name', 'Test User']);
+      fs.writeFileSync(path.join(repo, 'README.md'), '# Test\n');
+      runGit(repo, ['add', 'README.md']);
+      runGit(repo, ['commit', '-m', 'Initial commit']);
+
+      const hookLog = path.join(dataHome, 'post-checkout-skipped.log');
+      installPostCheckoutHook(
+        repo,
+        `#!/bin/sh\nprintf 'ran' > ${JSON.stringify(hookLog)}\n`,
+        false,
+      );
+
+      const created = await createWorktree(repo, {
+        mode: 'new',
+        worktreeName: 'hook-skip-test',
+        branchName: 'openchamber/hook-skip-test',
+        returnAfterDirectoryCreated: true,
+      });
+
+      await expect.poll(
+        async () => (await getWorktreeBootstrapStatus(created.path)).status,
+        { timeout: 5_000 },
+      ).toBe('ready');
+      expect(fs.existsSync(hookLog)).toBe(false);
+    } finally {
+      if (previousXdgDataHome === undefined) {
+        delete process.env.XDG_DATA_HOME;
+      } else {
+        process.env.XDG_DATA_HOME = previousXdgDataHome;
+      }
+    }
+  });
+
+  it('does not fail worktree bootstrap when the post-checkout hook fails', async () => {
+    if (!canRunGit()) return;
+
+    const previousXdgDataHome = process.env.XDG_DATA_HOME;
+    const dataHome = createTempDir();
+    process.env.XDG_DATA_HOME = dataHome;
+
+    try {
+      const repo = createTempDir();
+      runGit(repo, ['init', '-b', 'main']);
+      runGit(repo, ['config', 'user.email', 'test@example.com']);
+      runGit(repo, ['config', 'user.name', 'Test User']);
+      fs.writeFileSync(path.join(repo, 'README.md'), '# Test\n');
+      runGit(repo, ['add', 'README.md']);
+      runGit(repo, ['commit', '-m', 'Initial commit']);
+
+      const hookLog = path.join(dataHome, 'post-checkout-failed.log');
+      installPostCheckoutHook(
+        repo,
+        `#!/bin/sh\nprintf 'ran' > ${JSON.stringify(hookLog)}\nexit 1\n`,
+      );
+
+      const created = await createWorktree(repo, {
+        mode: 'new',
+        worktreeName: 'hook-fail-test',
+        branchName: 'openchamber/hook-fail-test',
+        returnAfterDirectoryCreated: true,
+      });
+
+      await expect.poll(
+        async () => (await getWorktreeBootstrapStatus(created.path)).status,
+        { timeout: 5_000 },
+      ).toBe('ready');
+      expect(fs.readFileSync(hookLog, 'utf8')).toBe('ran');
+    } finally {
+      if (previousXdgDataHome === undefined) {
+        delete process.env.XDG_DATA_HOME;
+      } else {
+        process.env.XDG_DATA_HOME = previousXdgDataHome;
+      }
+    }
+  });
+
   it('waits for active bootstrap work before removing a worktree', async () => {
     if (!canRunGit()) return;
 

From d8518bf05393d471cae27bd0ca30f9e93a53eeda Mon Sep 17 00:00:00 2001
From: deatheros <12375795+deatheros@users.noreply.github.com>
Date: Fri, 7 Aug 2026 01:49:44 +0300
Subject: [PATCH 51/57] fix(desktop): recover from macOS directory permission
 failures

---
 packages/electron/README.md                   |   1 +
 .../session/DirectoryExplorerDialog.tsx       |  52 +++++++--
 .../session/sidebar/DOCUMENTATION.md          |   1 +
 .../session/sidebar/SessionGroupSection.tsx   | 109 +++++++++++++-----
 packages/ui/src/hooks/useFileSystemAccess.ts  |  11 +-
 packages/ui/src/lib/api/files-errors.test.ts  |  28 +++++
 packages/ui/src/lib/api/files-errors.ts       |  40 +++++++
 packages/ui/src/lib/desktop.ts                |   9 +-
 packages/ui/src/lib/i18n/messages/de.ts       |   6 +
 packages/ui/src/lib/i18n/messages/en.ts       |   6 +
 packages/ui/src/lib/i18n/messages/es.ts       |   6 +
 packages/ui/src/lib/i18n/messages/fr.ts       |   6 +
 packages/ui/src/lib/i18n/messages/ja.ts       |   6 +
 packages/ui/src/lib/i18n/messages/ko.ts       |   6 +
 packages/ui/src/lib/i18n/messages/pl.ts       |   6 +
 packages/ui/src/lib/i18n/messages/pt-BR.ts    |   6 +
 packages/ui/src/lib/i18n/messages/uk.ts       |   6 +
 packages/ui/src/lib/i18n/messages/zh-CN.ts    |   6 +
 packages/ui/src/lib/i18n/messages/zh-TW.ts    |   6 +
 packages/ui/src/lib/opencode/client.ts        |  93 +++++++--------
 packages/ui/src/sync/DOCUMENTATION.md         |   1 +
 packages/ui/src/sync/child-store.test.ts      |  35 ++++++
 packages/ui/src/sync/child-store.ts           |  18 ++-
 packages/ui/src/sync/sync-context.tsx         |  17 ++-
 packages/web/server/lib/fs/DOCUMENTATION.md   |   1 +
 packages/web/server/lib/fs/routes.js          |  52 ++++++---
 packages/web/server/lib/fs/routes.test.js     |  15 +++
 packages/web/src/api/files.test.ts            |  28 +++++
 packages/web/src/api/files.ts                 |  25 +++-
 packages/web/vitest.config.ts                 |   1 +
 30 files changed, 497 insertions(+), 106 deletions(-)
 create mode 100644 packages/ui/src/lib/api/files-errors.test.ts
 create mode 100644 packages/ui/src/lib/api/files-errors.ts

diff --git a/packages/electron/README.md b/packages/electron/README.md
index 9b971a2b..ac05fabb 100644
--- a/packages/electron/README.md
+++ b/packages/electron/README.md
@@ -143,6 +143,7 @@ Use an explicit override when testing a different OpenCode CLI build or when a u
 - Floating Mini Chat windows.
 - Multiple native windows.
 - Native notifications.
+- User-confirmed local folder selection. The shared UI supplies the requested directory as the picker `defaultPath`; confirmation is required before filesystem access is retried.
 - One-click open/reveal/open-in-app actions.
 - Desktop host switcher and deep-link imports.
 - Local and remote instance handling.
diff --git a/packages/ui/src/components/session/DirectoryExplorerDialog.tsx b/packages/ui/src/components/session/DirectoryExplorerDialog.tsx
index 81d998a4..ba9d7bb6 100644
--- a/packages/ui/src/components/session/DirectoryExplorerDialog.tsx
+++ b/packages/ui/src/components/session/DirectoryExplorerDialog.tsx
@@ -22,6 +22,10 @@ import { MobileOverlayPanel } from '@/components/ui/MobileOverlayPanel';
 import { Icon } from "@/components/icon/Icon";
 import { opencodeClient } from '@/lib/opencode/client';
 import { useI18n } from '@/lib/i18n';
+import {
+  isFilesystemError,
+  type FilesystemErrorReason,
+} from '@/lib/api/files-errors';
 
 interface DirectoryExplorerDialogProps {
   open: boolean;
@@ -148,7 +152,7 @@ export const DirectoryExplorerDialog: React.FC<DirectoryExplorerDialogProps> = (
   const loadGitIdentityProfiles = useGitIdentitiesStore((s) => s.loadProfiles);
   const loadGlobalGitIdentity = useGitIdentitiesStore((s) => s.loadGlobalIdentity);
   const loadDefaultGitIdentityId = useGitIdentitiesStore((s) => s.loadDefaultGitIdentityId);
-  const { isDesktop, requestAccess, startAccessing } = useFileSystemAccess();
+  const { canRequestAccess, requestAccess, startAccessing } = useFileSystemAccess();
   const { isMobile } = useDeviceInfo();
   const inputRef = React.useRef<HTMLInputElement>(null);
   const addButtonRef = React.useRef<HTMLButtonElement>(null);
@@ -158,6 +162,8 @@ export const DirectoryExplorerDialog: React.FC<DirectoryExplorerDialogProps> = (
   const [entries, setEntries] = React.useState<BrowseEntry[]>([]);
   const [isLoading, setIsLoading] = React.useState(false);
   const [isBrowseDirectoryMissing, setIsBrowseDirectoryMissing] = React.useState(false);
+  const [browseErrorReason, setBrowseErrorReason] = React.useState<FilesystemErrorReason | null>(null);
+  const [browseReloadKey, setBrowseReloadKey] = React.useState(0);
   const [highlightedIndex, setHighlightedIndex] = React.useState(0);
   const [isConfirming, setIsConfirming] = React.useState(false);
   const [isOpeningFinder, setIsOpeningFinder] = React.useState(false);
@@ -250,16 +256,19 @@ export const DirectoryExplorerDialog: React.FC<DirectoryExplorerDialogProps> = (
   React.useEffect(() => {
     if (!open || !browseDirectoryAbsolutePath) {
       setEntries([]);
+      setBrowseErrorReason(null);
       return;
     }
 
     let cancelled = false;
     setIsLoading(true);
     setIsBrowseDirectoryMissing(false);
+    setBrowseErrorReason(null);
     opencodeClient.listLocalDirectory(browseDirectoryAbsolutePath)
       .then((result) => {
         if (cancelled) return;
         setIsBrowseDirectoryMissing(false);
+        setBrowseErrorReason(null);
         const nextEntries = result
           .filter((entry) => entry.isDirectory)
           .map((entry) => ({
@@ -269,10 +278,12 @@ export const DirectoryExplorerDialog: React.FC<DirectoryExplorerDialogProps> = (
           .sort((left, right) => left.name.localeCompare(right.name));
         setEntries(nextEntries);
       })
-      .catch(() => {
+      .catch((error) => {
         if (!cancelled) {
           setEntries([]);
-          setIsBrowseDirectoryMissing(true);
+          const reason = isFilesystemError(error) ? error.reason : 'unknown';
+          setBrowseErrorReason(reason);
+          setIsBrowseDirectoryMissing(reason === 'not-found');
         }
       })
       .finally(() => {
@@ -282,7 +293,7 @@ export const DirectoryExplorerDialog: React.FC<DirectoryExplorerDialogProps> = (
     return () => {
       cancelled = true;
     };
-  }, [browseDirectoryAbsolutePath, open]);
+  }, [browseDirectoryAbsolutePath, browseReloadKey, open]);
 
   const filteredEntries = React.useMemo(() => {
     const lowerFilter = browseFilterQuery.toLowerCase();
@@ -327,12 +338,19 @@ export const DirectoryExplorerDialog: React.FC<DirectoryExplorerDialogProps> = (
   const shouldCreateTarget = Boolean(
     targetPath
     && !isAlreadyAdded
+    && (browseErrorReason === null || browseErrorReason === 'not-found')
     && (
       (hasTrailingPathSeparator(query) && isBrowseDirectoryMissing)
       || (!hasTrailingPathSeparator(query) && browseFilterQuery.trim().length > 0 && exactEntry === null)
     )
   );
-  const canAddProject = !isConfirming && !isOpeningFinder && !isAlreadyAdded && Boolean(targetPath);
+  const canAddProject = !isConfirming
+    && !isOpeningFinder
+    && !isAlreadyAdded
+    && browseErrorReason !== 'os-permission'
+    && browseErrorReason !== 'invalid-response'
+    && browseErrorReason !== 'unknown'
+    && Boolean(targetPath);
   const canSubmitClone = canAddProject && cloneRemoteUrl.trim().length > 0;
   const highlightedRow = rows[highlightedIndex] ?? null;
   const hasHighlightedBrowseItem = Boolean(
@@ -459,7 +477,7 @@ export const DirectoryExplorerDialog: React.FC<DirectoryExplorerDialogProps> = (
   }, [browseToDisplayPath, browseToEntry]);
 
   const handleOpenInFinder = React.useCallback(async () => {
-    if (!isDesktop || isOpeningFinder) return;
+    if (!canRequestAccess || isOpeningFinder) return;
     setIsOpeningFinder(true);
     try {
       const result = await requestAccess(targetPath);
@@ -488,7 +506,7 @@ export const DirectoryExplorerDialog: React.FC<DirectoryExplorerDialogProps> = (
     } finally {
       setIsOpeningFinder(false);
     }
-  }, [finalizeSelection, isDesktop, isOpeningFinder, requestAccess, startAccessing, t, targetPath]);
+  }, [canRequestAccess, finalizeSelection, isOpeningFinder, requestAccess, startAccessing, t, targetPath]);
 
   const handleKeyDown = React.useCallback((event: React.KeyboardEvent<HTMLInputElement>) => {
     if (event.key === 'ArrowDown') {
@@ -596,6 +614,24 @@ export const DirectoryExplorerDialog: React.FC<DirectoryExplorerDialogProps> = (
           <div className="py-10 text-center typography-ui-label text-muted-foreground">
             {t('directoryExplorerDialog.browse.loading')}
           </div>
+        ) : browseErrorReason && browseErrorReason !== 'not-found' ? (
+          <div className="flex flex-col items-center gap-3 px-4 py-10 text-center">
+            <div className="typography-ui-label text-[var(--status-error-foreground)]">
+              {browseErrorReason === 'os-permission'
+                ? t('directoryExplorerDialog.browse.permissionDenied')
+                : t('directoryExplorerDialog.browse.loadFailed')}
+            </div>
+            <div className="flex items-center gap-2">
+              {browseErrorReason === 'os-permission' && canRequestAccess ? (
+                <Button size="xs" onClick={() => void handleOpenInFinder()} disabled={isOpeningFinder}>
+                  {t('directoryExplorerDialog.browse.grantAccess')}
+                </Button>
+              ) : null}
+              <Button variant="outline" size="xs" onClick={() => setBrowseReloadKey((key) => key + 1)}>
+                {t('directoryExplorerDialog.browse.retry')}
+              </Button>
+            </div>
+          </div>
         ) : rows.length === 0 ? (
           <div className="py-10 text-center typography-ui-label text-muted-foreground">
             {t('directoryExplorerDialog.browse.empty')}
@@ -688,7 +724,7 @@ export const DirectoryExplorerDialog: React.FC<DirectoryExplorerDialogProps> = (
     <>
       {!isMobile ? footerHints : null}
       <div className={cn('flex w-full flex-row justify-end gap-2 sm:w-auto', isMobile && 'justify-stretch')}>
-        {isDesktop ? (
+        {canRequestAccess ? (
           <Button variant="ghost" size="xs" onClick={handleOpenInFinder} disabled={isConfirming || isOpeningFinder || isCloneMode}>
             {isOpeningFinder ? t('directoryExplorerDialog.actions.openingFinder') : t('directoryExplorerDialog.actions.openInFinder')}
           </Button>
diff --git a/packages/ui/src/components/session/sidebar/DOCUMENTATION.md b/packages/ui/src/components/session/sidebar/DOCUMENTATION.md
index 180dd7f0..8f0dc321 100644
--- a/packages/ui/src/components/session/sidebar/DOCUMENTATION.md
+++ b/packages/ui/src/components/session/sidebar/DOCUMENTATION.md
@@ -78,4 +78,5 @@
 - Recent membership includes active root sessions immediately even when their last committed `time.updated` falls outside the 48-hour window. Children and archived sessions remain excluded, and inactive roots remain timestamp-based. The active-ID subscription is disabled while the sidebar is hidden and ignores retry/status detail changes, avoiding streaming-frequency rerenders.
 - Structural updates rebuild grouped nodes only for projects whose local sessions, worktrees, repository state, or branch changed; unchanged project sections preserve references so memoized group/session descendants skip the update wave.
 - Empty successful lists, unresolved loads, and failed loads are separate UI states. Failed groups expose Retry and retain prior data.
+- Directory permission failures remain visible even when stale sessions are retained. Flat groups inspect every represented root/worktree directory; local Desktop may open the native picker for the exact failed directory, while other runtimes keep the ordinary Retry action.
 - Pins and folder assignments are not pruned from the first startup snapshot or from optimistic mutations. Confirmed local deletion and routed external deletion clean immediately; a later authoritative omission after an established baseline covers missed external delete events.
diff --git a/packages/ui/src/components/session/sidebar/SessionGroupSection.tsx b/packages/ui/src/components/session/sidebar/SessionGroupSection.tsx
index 5fb82420..1a7e7304 100644
--- a/packages/ui/src/components/session/sidebar/SessionGroupSection.tsx
+++ b/packages/ui/src/components/session/sidebar/SessionGroupSection.tsx
@@ -9,6 +9,7 @@ const ARCHIVED_VIRTUALIZE_THRESHOLD = 50;
 // around 24-32px; virtua measures mounted rows and uses this as the initial hint.
 const ARCHIVED_ROW_ESTIMATE_PX = 28;
 import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip';
+import { Button } from '@/components/ui/button';
 import { Icon } from "@/components/icon/Icon";
 import { cn } from '@/lib/utils';
 import { sessionEvents } from '@/lib/sessionEvents';
@@ -32,6 +33,7 @@ import { useSessionFoldersStore } from '@/stores/useSessionFoldersStore';
 import { getGitHubPrStatusKey, usePrVisualSummary } from '@/stores/useGitHubPrStatusStore';
 import { useI18n } from '@/lib/i18n';
 import { useChildStoreManager } from '@/sync/sync-context';
+import { canRequestNativeDirectoryAccess, requestDirectoryAccess } from '@/lib/desktop';
 import { CollapsedActivityIndicator } from './collapsedActivityIndicator';
 import {
   getSessionNodesActivityState,
@@ -348,18 +350,57 @@ function SessionGroupSectionBase(props: Props): React.ReactNode {
   const groupPrSummary = usePrVisualSummary(groupPrKey);
   const groupPrColor = groupPrSummary ? `var(--pr-${groupPrSummary.visualState})` : undefined;
   const childStores = useChildStoreManager();
-  const bootstrapDirectory = normalizePath(group.directory ?? null);
-  const bootstrapState = React.useSyncExternalStore(
+  const bootstrapDirectories = React.useMemo(() => {
+    const directories = group.folderScopes?.map((scope) => normalizePath(scope.directory))
+      ?? [normalizePath(group.directory ?? null)];
+    return [...new Set(directories.filter((directory): directory is string => Boolean(directory)))];
+  }, [group.directory, group.folderScopes]);
+  React.useSyncExternalStore(
     React.useCallback(
-      (notify) => bootstrapDirectory ? childStores.subscribeBootstrap(notify) : () => undefined,
-      [bootstrapDirectory, childStores],
+      (notify) => bootstrapDirectories.length > 0 ? childStores.subscribeBootstrap(notify) : () => undefined,
+      [bootstrapDirectories.length, childStores],
     ),
     React.useCallback(
-      () => bootstrapDirectory ? childStores.getBootstrapState(bootstrapDirectory) : undefined,
-      [bootstrapDirectory, childStores],
+      () => bootstrapDirectories.map((directory) => (
+        `${directory}\u0000${childStores.getBootstrapState(directory) ?? ''}\u0000${childStores.getBootstrapFailure(directory) ?? ''}`
+      )).join('\u0001'),
+      [bootstrapDirectories, childStores],
     ),
-    React.useCallback(() => undefined, []),
+    React.useCallback(() => '', []),
   );
+  const bootstrapLoading = bootstrapDirectories.some((directory) => {
+    const state = childStores.getBootstrapState(directory);
+    return state === 'queued' || state === 'running';
+  });
+  const failedBootstrapDirectory = bootstrapDirectories.find(
+    (directory) => childStores.getBootstrapState(directory) === 'failed',
+  ) ?? null;
+  const bootstrapFailure = failedBootstrapDirectory
+    ? childStores.getBootstrapFailure(failedBootstrapDirectory)
+    : undefined;
+  const canGrantBootstrapAccess = bootstrapFailure === 'os-permission' && canRequestNativeDirectoryAccess();
+  const [isRequestingBootstrapAccess, setIsRequestingBootstrapAccess] = React.useState(false);
+
+  const retryFailedBootstrap = React.useCallback(() => {
+    if (!failedBootstrapDirectory) return;
+    childStores.requestBootstrap({
+      directory: failedBootstrapDirectory,
+      priority: isCollapsed ? 'visible' : 'expanded',
+      reason: group.isMain ? 'project-expanded' : 'worktree-expanded',
+      force: true,
+    });
+  }, [childStores, failedBootstrapDirectory, group.isMain, isCollapsed]);
+
+  const grantFailedBootstrapAccess = React.useCallback(async () => {
+    if (!failedBootstrapDirectory || !canGrantBootstrapAccess || isRequestingBootstrapAccess) return;
+    setIsRequestingBootstrapAccess(true);
+    try {
+      const result = await requestDirectoryAccess(failedBootstrapDirectory);
+      if (result.success) retryFailedBootstrap();
+    } finally {
+      setIsRequestingBootstrapAccess(false);
+    }
+  }, [canGrantBootstrapAccess, failedBootstrapDirectory, isRequestingBootstrapAccess, retryFailedBootstrap]);
   const maxVisible = hideDirectoryControls ? 10 : 5;
   const nonArchivedVisibleCount = Math.max(maxVisible, visibleSessionCount ?? maxVisible);
   const groupMatchesSearch = hasSessionSearchQuery ? searchData?.groupMatches === true : false;
@@ -879,6 +920,33 @@ function SessionGroupSectionBase(props: Props): React.ReactNode {
         ? 'pr-2 group-hover/gh:pr-14 group-focus-within/gh:pr-14'
         : 'pr-2 group-hover/gh:pr-7 group-focus-within/gh:pr-7');
 
+  const bootstrapFailureNotice = failedBootstrapDirectory ? (
+    <span className="inline-flex flex-wrap items-center gap-1.5">
+      {bootstrapFailure === 'os-permission'
+        ? t('sessions.sidebar.group.empty.permissionDenied')
+        : t('sessions.sidebar.group.empty.loadFailed')}
+      {canGrantBootstrapAccess ? (
+        <Button
+          variant="link"
+          size="xs"
+          className="h-auto p-0 typography-micro"
+          disabled={isRequestingBootstrapAccess}
+          onClick={() => void grantFailedBootstrapAccess()}
+        >
+          {t('sessions.sidebar.group.empty.grantAccess')}
+        </Button>
+      ) : null}
+      <Button
+        variant="link"
+        size="xs"
+        className="h-auto p-0 typography-micro"
+        onClick={retryFailedBootstrap}
+      >
+        {t('sessions.sidebar.group.empty.retry')}
+      </Button>
+    </span>
+  ) : null;
+
   const body = (
     <SessionFolderDndScope
       scopeKey={folderScopes[0]?.scopeKey ?? folderScopeKey}
@@ -971,34 +1039,23 @@ function SessionGroupSectionBase(props: Props): React.ReactNode {
         <div className="py-1 pl-[26px] text-left typography-micro text-muted-foreground">
           {group.isArchivedBucket
             ? t('sessions.sidebar.group.empty.noArchivedSessions')
-            : bootstrapState === 'queued' || bootstrapState === 'running'
+            : bootstrapLoading
               ? (
                 <span className="inline-flex items-center gap-1.5">
                   <Icon name="loader-4" className="size-3 animate-spin" />
                   {t('sessions.sidebar.group.empty.loadingSessions')}
                 </span>
               )
-              : bootstrapState === 'failed' && bootstrapDirectory
-                ? (
-                  <span className="inline-flex items-center gap-1.5">
-                    {t('sessions.sidebar.group.empty.loadFailed')}
-                    <button
-                      type="button"
-                      className="text-foreground hover:underline"
-                      onClick={() => childStores.requestBootstrap({
-                        directory: bootstrapDirectory,
-                        priority: isCollapsed ? 'visible' : 'expanded',
-                        reason: group.isMain ? 'project-expanded' : 'worktree-expanded',
-                        force: true,
-                      })}
-                    >
-                      {t('sessions.sidebar.group.empty.retry')}
-                    </button>
-                  </span>
-                )
+              : bootstrapFailureNotice
+                ? bootstrapFailureNotice
             : t('sessions.sidebar.group.empty.noSessionsInWorkspace')}
         </div>
       ) : null}
+      {totalSessions > 0 && bootstrapFailureNotice ? (
+        <div className="py-1 pl-[26px] text-left typography-micro text-[var(--status-error-foreground)]">
+          {bootstrapFailureNotice}
+        </div>
+      ) : null}
       {remainingCount > 0 ? (
         <button
           type="button"
diff --git a/packages/ui/src/hooks/useFileSystemAccess.ts b/packages/ui/src/hooks/useFileSystemAccess.ts
index 773c6ab7..1b3b9852 100644
--- a/packages/ui/src/hooks/useFileSystemAccess.ts
+++ b/packages/ui/src/hooks/useFileSystemAccess.ts
@@ -1,11 +1,19 @@
 import { useCallback, useEffect, useState } from 'react';
-import { isDesktopShell, requestDirectoryAccess, startAccessingDirectory, stopAccessingDirectory } from '@/lib/desktop';
+import {
+  canRequestNativeDirectoryAccess,
+  isDesktopShell,
+  requestDirectoryAccess,
+  startAccessingDirectory,
+  stopAccessingDirectory,
+} from '@/lib/desktop';
 
 export const useFileSystemAccess = () => {
   const [isDesktop, setIsDesktop] = useState(false);
+  const [canRequestAccess, setCanRequestAccess] = useState(false);
 
   useEffect(() => {
     setIsDesktop(isDesktopShell());
+    setCanRequestAccess(canRequestNativeDirectoryAccess());
   }, []);
 
   const requestAccess = useCallback(async (directoryPath: string): Promise<{ success: boolean; path?: string; projectId?: string; error?: string }> => {
@@ -34,6 +42,7 @@ export const useFileSystemAccess = () => {
 
   return {
     isDesktop,
+    canRequestAccess,
     requestAccess,
     startAccessing,
     stopAccessing
diff --git a/packages/ui/src/lib/api/files-errors.test.ts b/packages/ui/src/lib/api/files-errors.test.ts
new file mode 100644
index 00000000..6d54d837
--- /dev/null
+++ b/packages/ui/src/lib/api/files-errors.test.ts
@@ -0,0 +1,28 @@
+import { describe, expect, test } from 'bun:test';
+
+import {
+  FilesystemError,
+  isFilesystemError,
+  parseFilesystemErrorReason,
+} from './files-errors';
+
+describe('FilesystemError', () => {
+  test('retains a stable reason and HTTP status', () => {
+    const error = new FilesystemError('Access denied', {
+      reason: 'os-permission',
+      status: 403,
+    });
+
+    expect(isFilesystemError(error)).toBe(true);
+    expect(error.name).toBe('FilesystemError');
+    expect(error.message).toBe('Access denied');
+    expect(error.reason).toBe('os-permission');
+    expect(error.status).toBe(403);
+  });
+
+  test('normalizes unsupported response reasons to unknown', () => {
+    expect(parseFilesystemErrorReason('os-permission')).toBe('os-permission');
+    expect(parseFilesystemErrorReason('made-up')).toBe('unknown');
+    expect(parseFilesystemErrorReason(undefined)).toBe('unknown');
+  });
+});
diff --git a/packages/ui/src/lib/api/files-errors.ts b/packages/ui/src/lib/api/files-errors.ts
new file mode 100644
index 00000000..bdac478a
--- /dev/null
+++ b/packages/ui/src/lib/api/files-errors.ts
@@ -0,0 +1,40 @@
+export type FilesystemErrorReason =
+  | 'os-permission'
+  | 'not-found'
+  | 'not-directory'
+  | 'invalid-response'
+  | 'unknown';
+
+export class FilesystemError extends Error {
+  readonly reason: FilesystemErrorReason;
+  readonly status?: number;
+
+  constructor(message: string, options: { reason?: FilesystemErrorReason; status?: number } = {}) {
+    super(message);
+    this.name = 'FilesystemError';
+    this.reason = options.reason ?? 'unknown';
+    this.status = options.status;
+  }
+}
+
+export const isFilesystemError = (error: unknown): error is FilesystemError => (
+  error instanceof FilesystemError
+  || Boolean(
+    error
+    && typeof error === 'object'
+    && 'reason' in error
+    && typeof (error as { reason?: unknown }).reason === 'string'
+  )
+);
+
+export const parseFilesystemErrorReason = (value: unknown): FilesystemErrorReason => {
+  switch (value) {
+    case 'os-permission':
+    case 'not-found':
+    case 'not-directory':
+    case 'invalid-response':
+      return value;
+    default:
+      return 'unknown';
+  }
+};
diff --git a/packages/ui/src/lib/desktop.ts b/packages/ui/src/lib/desktop.ts
index a1614127..e7885dae 100644
--- a/packages/ui/src/lib/desktop.ts
+++ b/packages/ui/src/lib/desktop.ts
@@ -531,6 +531,10 @@ export const isDesktopShell = (): boolean => {
   return isElectronShell();
 };
 
+export const canRequestNativeDirectoryAccess = (): boolean => (
+  isDesktopShell() && hasDesktopInvoke() && isDesktopLocalOriginActive()
+);
+
 export const startDesktopWindowDrag = async (): Promise<boolean> => {
   if (!isDesktopShell()) {
     return false;
@@ -586,12 +590,13 @@ export const requestDirectoryAccess = async (
   directoryPath: string
 ): Promise<{ success: boolean; path?: string; projectId?: string; error?: string }> => {
   // Desktop shell on local instance: use native folder picker.
-  if (hasDesktopInvoke() && isDesktopLocalOriginActive()) {
+  if (canRequestNativeDirectoryAccess()) {
     try {
       const selected = await getDesktopBridge()?.openDialog?.({
         directory: true,
         multiple: false,
         title: 'Select Working Directory',
+        ...(directoryPath ? { defaultPath: directoryPath } : {}),
       });
       if (!selected || typeof selected !== 'string') {
         return { success: false, error: 'Directory selection cancelled' };
@@ -603,7 +608,7 @@ export const requestDirectoryAccess = async (
     }
   }
 
-  return { success: true, path: directoryPath };
+  return { success: false, error: 'Native directory picker not available' };
 };
 
 const isDesktopFileGrantResult = (
diff --git a/packages/ui/src/lib/i18n/messages/de.ts b/packages/ui/src/lib/i18n/messages/de.ts
index f4f36c89..d26bc6c7 100644
--- a/packages/ui/src/lib/i18n/messages/de.ts
+++ b/packages/ui/src/lib/i18n/messages/de.ts
@@ -1499,6 +1499,10 @@ export const dict = {
   'directoryExplorerDialog.browse.directories': 'Verzeichnisse',
   'directoryExplorerDialog.browse.loading': 'Lade Verzeichnisse...',
   'directoryExplorerDialog.browse.empty': 'Keine passenden Verzeichnisse.',
+  'directoryExplorerDialog.browse.permissionDenied': 'OpenChamber benötigt Zugriff auf diesen Ordner.',
+  'directoryExplorerDialog.browse.loadFailed': 'Dieser Ordner konnte nicht geladen werden.',
+  'directoryExplorerDialog.browse.grantAccess': 'Zugriff gewähren',
+  'directoryExplorerDialog.browse.retry': 'Erneut versuchen',
   'directoryExplorerDialog.browse.parentDirectory': 'Übergeordnetes Verzeichnis',
   'directoryExplorerDialog.browse.addedBadge': 'Hinzugefügt',
   'directoryExplorerDialog.browse.quickAdd': 'Hinzufügen',
@@ -2924,6 +2928,8 @@ export const dict = {
   'sessions.sidebar.group.empty.loadingSessions': 'Sitzungen werden geladen...',
   'sessions.sidebar.group.empty.loadFailed': 'Sitzungen konnten nicht geladen werden',
   'sessions.sidebar.group.empty.retry': 'Erneut versuchen',
+  'sessions.sidebar.group.empty.permissionDenied': 'Ordnerzugriff ist erforderlich.',
+  'sessions.sidebar.group.empty.grantAccess': 'Zugriff gewähren',
   'chat.messageBody.actions.pinContext': 'Kontext anheften',
   'chat.messageBody.actions.unpinContext': 'Kontext lösen',
   'chat.messageBody.actions.contextPinFailed': 'Kontext konnte nicht angeheftet werden',
diff --git a/packages/ui/src/lib/i18n/messages/en.ts b/packages/ui/src/lib/i18n/messages/en.ts
index a422daf0..fd3b05b1 100644
--- a/packages/ui/src/lib/i18n/messages/en.ts
+++ b/packages/ui/src/lib/i18n/messages/en.ts
@@ -1656,6 +1656,10 @@ export const dict = {
   'directoryExplorerDialog.browse.directories': 'Directories',
   'directoryExplorerDialog.browse.loading': 'Loading directories...',
   'directoryExplorerDialog.browse.empty': 'No matching directories.',
+  'directoryExplorerDialog.browse.permissionDenied': 'OpenChamber needs access to this folder.',
+  'directoryExplorerDialog.browse.loadFailed': 'Could not load this folder.',
+  'directoryExplorerDialog.browse.grantAccess': 'Grant access',
+  'directoryExplorerDialog.browse.retry': 'Try again',
   'directoryExplorerDialog.browse.parentDirectory': 'Parent directory',
   'directoryExplorerDialog.browse.addedBadge': 'Added',
   'directoryExplorerDialog.browse.quickAdd': 'Add',
@@ -2007,6 +2011,8 @@ export const dict = {
   'sessions.sidebar.group.empty.loadingSessions': 'Loading sessions…',
   'sessions.sidebar.group.empty.loadFailed': 'Could not refresh sessions.',
   'sessions.sidebar.group.empty.retry': 'Try again',
+  'sessions.sidebar.group.empty.permissionDenied': 'Folder access is required.',
+  'sessions.sidebar.group.empty.grantAccess': 'Grant access',
   'chat.unifiedControls.title': 'Controls',
   'chat.unifiedControls.model.title': 'Model',
   'chat.unifiedControls.model.noRecent': 'No recent models',
diff --git a/packages/ui/src/lib/i18n/messages/es.ts b/packages/ui/src/lib/i18n/messages/es.ts
index 7900e334..3d362620 100644
--- a/packages/ui/src/lib/i18n/messages/es.ts
+++ b/packages/ui/src/lib/i18n/messages/es.ts
@@ -1634,6 +1634,10 @@ export const dict: Record<I18nKey, string> = {
   "directoryExplorerDialog.browse.directories": "Directorios",
   "directoryExplorerDialog.browse.loading": "Cargando directorios...",
   "directoryExplorerDialog.browse.empty": "No hay directorios coincidentes.",
+  "directoryExplorerDialog.browse.permissionDenied": "OpenChamber necesita acceso a esta carpeta.",
+  "directoryExplorerDialog.browse.loadFailed": "No se pudo cargar esta carpeta.",
+  "directoryExplorerDialog.browse.grantAccess": "Permitir acceso",
+  "directoryExplorerDialog.browse.retry": "Reintentar",
   "directoryExplorerDialog.browse.parentDirectory": "Directorio padre",
   "directoryExplorerDialog.browse.addedBadge": "Añadido",
   "directoryExplorerDialog.browse.quickAdd": "Añadir",
@@ -1985,6 +1989,8 @@ export const dict: Record<I18nKey, string> = {
   "sessions.sidebar.group.empty.loadingSessions": "Cargando sesiones…",
   "sessions.sidebar.group.empty.loadFailed": "No se pudieron actualizar las sesiones.",
   "sessions.sidebar.group.empty.retry": "Reintentar",
+  "sessions.sidebar.group.empty.permissionDenied": "Se requiere acceso a la carpeta.",
+  "sessions.sidebar.group.empty.grantAccess": "Permitir acceso",
   "chat.unifiedControls.title": "Controles",
   "chat.unifiedControls.model.title": "Modelo",
   "chat.unifiedControls.model.noRecent": "No hay modelos recientes",
diff --git a/packages/ui/src/lib/i18n/messages/fr.ts b/packages/ui/src/lib/i18n/messages/fr.ts
index db497268..d85c260c 100644
--- a/packages/ui/src/lib/i18n/messages/fr.ts
+++ b/packages/ui/src/lib/i18n/messages/fr.ts
@@ -1469,6 +1469,10 @@ export const dict = {
   'directoryExplorerDialog.browse.directories': 'Annuaires',
   'directoryExplorerDialog.browse.loading': 'Chargement des répertoires...',
   'directoryExplorerDialog.browse.empty': 'Aucun répertoire correspondant.',
+  'directoryExplorerDialog.browse.permissionDenied': 'OpenChamber doit accéder à ce dossier.',
+  'directoryExplorerDialog.browse.loadFailed': 'Impossible de charger ce dossier.',
+  'directoryExplorerDialog.browse.grantAccess': 'Autoriser l’accès',
+  'directoryExplorerDialog.browse.retry': 'Réessayer',
   'directoryExplorerDialog.browse.parentDirectory': 'Annuaire parent',
   'directoryExplorerDialog.browse.addedBadge': 'Ajouté',
   'directoryExplorerDialog.browse.quickAdd': 'Ajouter',
@@ -1794,6 +1798,8 @@ export const dict = {
   'sessions.sidebar.group.empty.loadingSessions': 'Chargement des sessions…',
   'sessions.sidebar.group.empty.loadFailed': 'Impossible d’actualiser les sessions.',
   'sessions.sidebar.group.empty.retry': 'Réessayer',
+  'sessions.sidebar.group.empty.permissionDenied': 'L’accès au dossier est requis.',
+  'sessions.sidebar.group.empty.grantAccess': 'Autoriser l’accès',
   'chat.unifiedControls.title': 'Contrôles',
   'chat.unifiedControls.model.title': 'Modèle',
   'chat.unifiedControls.model.noRecent': 'Aucun modèle récent',
diff --git a/packages/ui/src/lib/i18n/messages/ja.ts b/packages/ui/src/lib/i18n/messages/ja.ts
index b9052c09..e2da8965 100644
--- a/packages/ui/src/lib/i18n/messages/ja.ts
+++ b/packages/ui/src/lib/i18n/messages/ja.ts
@@ -1652,6 +1652,10 @@ export const dict: Record<I18nKey, string> = {
   'directoryExplorerDialog.browse.directories': 'ディレクトリ',
   'directoryExplorerDialog.browse.loading': 'ディレクトリを読み込み中...',
   'directoryExplorerDialog.browse.empty': '一致するディレクトリがありません。',
+  'directoryExplorerDialog.browse.permissionDenied': 'OpenChamber がこのフォルダにアクセスする必要があります。',
+  'directoryExplorerDialog.browse.loadFailed': 'このフォルダを読み込めませんでした。',
+  'directoryExplorerDialog.browse.grantAccess': 'アクセスを許可',
+  'directoryExplorerDialog.browse.retry': '再試行',
   'directoryExplorerDialog.browse.parentDirectory': '親ディレクトリ',
   'directoryExplorerDialog.browse.addedBadge': '追加済み',
   'directoryExplorerDialog.browse.quickAdd': '追加',
@@ -2003,6 +2007,8 @@ export const dict: Record<I18nKey, string> = {
   'sessions.sidebar.group.empty.loadingSessions': 'セッションを読み込んでいます…',
   'sessions.sidebar.group.empty.loadFailed': 'セッションを更新できませんでした。',
   'sessions.sidebar.group.empty.retry': '再試行',
+  'sessions.sidebar.group.empty.permissionDenied': 'フォルダへのアクセスが必要です。',
+  'sessions.sidebar.group.empty.grantAccess': 'アクセスを許可',
   'chat.unifiedControls.title': 'コントロール',
   'chat.unifiedControls.model.title': 'モデル',
   'chat.unifiedControls.model.noRecent': '最近のモデルはありません',
diff --git a/packages/ui/src/lib/i18n/messages/ko.ts b/packages/ui/src/lib/i18n/messages/ko.ts
index 902d2a60..d9d211d9 100644
--- a/packages/ui/src/lib/i18n/messages/ko.ts
+++ b/packages/ui/src/lib/i18n/messages/ko.ts
@@ -1658,6 +1658,10 @@ export const dict: Record<I18nKey, string> = {
   'directoryExplorerDialog.browse.directories': '디렉터리',
   'directoryExplorerDialog.browse.loading': '디렉터리 로드 중...',
   'directoryExplorerDialog.browse.empty': '일치하는 디렉터리가 없습니다.',
+  'directoryExplorerDialog.browse.permissionDenied': 'OpenChamber에서 이 폴더에 접근해야 합니다.',
+  'directoryExplorerDialog.browse.loadFailed': '이 폴더를 불러올 수 없습니다.',
+  'directoryExplorerDialog.browse.grantAccess': '접근 허용',
+  'directoryExplorerDialog.browse.retry': '다시 시도',
   'directoryExplorerDialog.browse.parentDirectory': '상위 디렉터리',
   'directoryExplorerDialog.browse.addedBadge': '추가됨',
   'directoryExplorerDialog.browse.quickAdd': '추가',
@@ -2009,6 +2013,8 @@ export const dict: Record<I18nKey, string> = {
   'sessions.sidebar.group.empty.loadingSessions': '세션을 불러오는 중…',
   'sessions.sidebar.group.empty.loadFailed': '세션을 새로 고칠 수 없습니다.',
   'sessions.sidebar.group.empty.retry': '다시 시도',
+  'sessions.sidebar.group.empty.permissionDenied': '폴더 접근이 필요합니다.',
+  'sessions.sidebar.group.empty.grantAccess': '접근 허용',
   'chat.unifiedControls.title': '컨트롤',
   'chat.unifiedControls.model.title': '모델',
   'chat.unifiedControls.model.noRecent': '최근 모델 없음',
diff --git a/packages/ui/src/lib/i18n/messages/pl.ts b/packages/ui/src/lib/i18n/messages/pl.ts
index 4865d153..26b5b47c 100644
--- a/packages/ui/src/lib/i18n/messages/pl.ts
+++ b/packages/ui/src/lib/i18n/messages/pl.ts
@@ -811,6 +811,8 @@ export const dict: Record<I18nKey, string> = {
   'sessions.sidebar.group.empty.loadingSessions': 'Wczytywanie sesji…',
   'sessions.sidebar.group.empty.loadFailed': 'Nie udało się odświeżyć sesji.',
   'sessions.sidebar.group.empty.retry': 'Spróbuj ponownie',
+  'sessions.sidebar.group.empty.permissionDenied': 'Wymagany jest dostęp do folderu.',
+  'sessions.sidebar.group.empty.grantAccess': 'Przyznaj dostęp',
   'chat.unifiedControls.title': 'Kontrolki',
   'chat.unifiedControls.model.title': 'Model',
   'chat.unifiedControls.model.noRecent': 'Brak ostatnich modeli',
@@ -1738,6 +1740,10 @@ export const dict: Record<I18nKey, string> = {
   'directoryExplorerDialog.browse.quickAdd': 'Dodaj',
   'directoryExplorerDialog.browse.directories': 'Katalogi',
   'directoryExplorerDialog.browse.empty': 'Brak pasujących katalogów.',
+  'directoryExplorerDialog.browse.permissionDenied': 'OpenChamber potrzebuje dostępu do tego folderu.',
+  'directoryExplorerDialog.browse.loadFailed': 'Nie udało się wczytać tego folderu.',
+  'directoryExplorerDialog.browse.grantAccess': 'Przyznaj dostęp',
+  'directoryExplorerDialog.browse.retry': 'Spróbuj ponownie',
   'directoryExplorerDialog.browse.loading': 'Ładowanie katalogów...',
   'directoryExplorerDialog.browse.parentDirectory': 'Katalog nadrzędny',
   'directoryExplorerDialog.description': 'Wybierz folder, który chcesz dodać jako projekt.',
diff --git a/packages/ui/src/lib/i18n/messages/pt-BR.ts b/packages/ui/src/lib/i18n/messages/pt-BR.ts
index ac04e32d..2ad738e9 100644
--- a/packages/ui/src/lib/i18n/messages/pt-BR.ts
+++ b/packages/ui/src/lib/i18n/messages/pt-BR.ts
@@ -1634,6 +1634,10 @@ export const dict: Record<I18nKey, string> = {
   "directoryExplorerDialog.browse.directories": "Diretórios",
   "directoryExplorerDialog.browse.loading": "Carregando diretórios...",
   "directoryExplorerDialog.browse.empty": "Nenhum diretório correspondente.",
+  "directoryExplorerDialog.browse.permissionDenied": "OpenChamber precisa acessar esta pasta.",
+  "directoryExplorerDialog.browse.loadFailed": "Não foi possível carregar esta pasta.",
+  "directoryExplorerDialog.browse.grantAccess": "Conceder acesso",
+  "directoryExplorerDialog.browse.retry": "Tentar novamente",
   "directoryExplorerDialog.browse.parentDirectory": "Diretório pai",
   "directoryExplorerDialog.browse.addedBadge": "Adicionado",
   "directoryExplorerDialog.browse.quickAdd": "Adicionar",
@@ -1985,6 +1989,8 @@ export const dict: Record<I18nKey, string> = {
   "sessions.sidebar.group.empty.loadingSessions": "Carregando sessões…",
   "sessions.sidebar.group.empty.loadFailed": "Não foi possível atualizar as sessões.",
   "sessions.sidebar.group.empty.retry": "Tentar novamente",
+  "sessions.sidebar.group.empty.permissionDenied": "É necessário acesso à pasta.",
+  "sessions.sidebar.group.empty.grantAccess": "Conceder acesso",
   "chat.unifiedControls.title": "Controles",
   "chat.unifiedControls.model.title": "Modelo",
   "chat.unifiedControls.model.noRecent": "Não há modelos recentes",
diff --git a/packages/ui/src/lib/i18n/messages/uk.ts b/packages/ui/src/lib/i18n/messages/uk.ts
index 89bf82d5..2760c77a 100644
--- a/packages/ui/src/lib/i18n/messages/uk.ts
+++ b/packages/ui/src/lib/i18n/messages/uk.ts
@@ -1634,6 +1634,10 @@ export const dict: Record<I18nKey, string> = {
   "directoryExplorerDialog.browse.directories": "Каталоги",
   "directoryExplorerDialog.browse.loading": "Завантаження каталогів...",
   "directoryExplorerDialog.browse.empty": "Немає відповідних каталогів.",
+  "directoryExplorerDialog.browse.permissionDenied": "OpenChamber потрібен доступ до цієї папки.",
+  "directoryExplorerDialog.browse.loadFailed": "Не вдалося завантажити цю папку.",
+  "directoryExplorerDialog.browse.grantAccess": "Надати доступ",
+  "directoryExplorerDialog.browse.retry": "Спробувати знову",
   "directoryExplorerDialog.browse.parentDirectory": "Батьківський каталог",
   "directoryExplorerDialog.browse.addedBadge": "Додано",
   "directoryExplorerDialog.browse.quickAdd": "Додати",
@@ -1985,6 +1989,8 @@ export const dict: Record<I18nKey, string> = {
   "sessions.sidebar.group.empty.loadingSessions": "Завантаження сесій…",
   "sessions.sidebar.group.empty.loadFailed": "Не вдалося оновити сесії.",
   "sessions.sidebar.group.empty.retry": "Спробувати знову",
+  "sessions.sidebar.group.empty.permissionDenied": "Потрібен доступ до папки.",
+  "sessions.sidebar.group.empty.grantAccess": "Надати доступ",
   "chat.unifiedControls.title": "Елементи керування",
   "chat.unifiedControls.model.title": "Модель",
   "chat.unifiedControls.model.noRecent": "Немає останніх моделей",
diff --git a/packages/ui/src/lib/i18n/messages/zh-CN.ts b/packages/ui/src/lib/i18n/messages/zh-CN.ts
index c08cde70..72aa8057 100644
--- a/packages/ui/src/lib/i18n/messages/zh-CN.ts
+++ b/packages/ui/src/lib/i18n/messages/zh-CN.ts
@@ -1622,6 +1622,10 @@ export const dict: Record<I18nKey, string> = {
   'directoryExplorerDialog.browse.directories': '目录',
   'directoryExplorerDialog.browse.loading': '正在加载目录...',
   'directoryExplorerDialog.browse.empty': '没有匹配的目录。',
+  'directoryExplorerDialog.browse.permissionDenied': 'OpenChamber 需要访问此文件夹。',
+  'directoryExplorerDialog.browse.loadFailed': '无法加载此文件夹。',
+  'directoryExplorerDialog.browse.grantAccess': '授予访问权限',
+  'directoryExplorerDialog.browse.retry': '重试',
   'directoryExplorerDialog.browse.parentDirectory': '上级目录',
   'directoryExplorerDialog.browse.addedBadge': '已添加',
   'directoryExplorerDialog.browse.quickAdd': '添加',
@@ -1973,6 +1977,8 @@ export const dict: Record<I18nKey, string> = {
   'sessions.sidebar.group.empty.loadingSessions': '正在加载会话…',
   'sessions.sidebar.group.empty.loadFailed': '无法刷新会话。',
   'sessions.sidebar.group.empty.retry': '重试',
+  'sessions.sidebar.group.empty.permissionDenied': '需要文件夹访问权限。',
+  'sessions.sidebar.group.empty.grantAccess': '授予访问权限',
   'chat.unifiedControls.title': '控制',
   'chat.unifiedControls.model.title': '模型',
   'chat.unifiedControls.model.noRecent': '没有最近使用的模型',
diff --git a/packages/ui/src/lib/i18n/messages/zh-TW.ts b/packages/ui/src/lib/i18n/messages/zh-TW.ts
index b1dcaeb8..d5106633 100644
--- a/packages/ui/src/lib/i18n/messages/zh-TW.ts
+++ b/packages/ui/src/lib/i18n/messages/zh-TW.ts
@@ -1626,6 +1626,10 @@ export const dict: Record<I18nKey, string> = {
   'directoryExplorerDialog.browse.directories': '目錄',
   'directoryExplorerDialog.browse.loading': '正在載入目錄...',
   'directoryExplorerDialog.browse.empty': '沒有符合的目錄。',
+  'directoryExplorerDialog.browse.permissionDenied': 'OpenChamber 需要存取此資料夾。',
+  'directoryExplorerDialog.browse.loadFailed': '無法載入此資料夾。',
+  'directoryExplorerDialog.browse.grantAccess': '授予存取權限',
+  'directoryExplorerDialog.browse.retry': '再試一次',
   'directoryExplorerDialog.browse.parentDirectory': '上層目錄',
   'directoryExplorerDialog.browse.addedBadge': '已新增',
   'directoryExplorerDialog.browse.quickAdd': '添加',
@@ -1977,6 +1981,8 @@ export const dict: Record<I18nKey, string> = {
   'sessions.sidebar.group.empty.loadingSessions': '正在載入工作階段…',
   'sessions.sidebar.group.empty.loadFailed': '無法重新整理工作階段。',
   'sessions.sidebar.group.empty.retry': '再試一次',
+  'sessions.sidebar.group.empty.permissionDenied': '需要資料夾存取權限。',
+  'sessions.sidebar.group.empty.grantAccess': '授予存取權限',
   'chat.unifiedControls.title': '控制',
   'chat.unifiedControls.model.title': '模型',
   'chat.unifiedControls.model.noRecent': '沒有最近使用的模型',
diff --git a/packages/ui/src/lib/opencode/client.ts b/packages/ui/src/lib/opencode/client.ts
index 7b618f4a..9693618a 100644
--- a/packages/ui/src/lib/opencode/client.ts
+++ b/packages/ui/src/lib/opencode/client.ts
@@ -13,6 +13,7 @@ import type {
   FilePartInput,
 } from "@opencode-ai/sdk/v2";
 import { isAmbiguousTransportFailure, markAmbiguousTransportFailure } from "@/lib/relay/transport-error";
+import { FilesystemError, parseFilesystemErrorReason } from "@/lib/api/files-errors";
 import type { PermissionRequest } from "@/types/permission";
 import type { QuestionRequest } from "@/types/question";
 
@@ -1751,20 +1752,55 @@ class OpencodeService {
     }
 
     const task = (async () => {
-    const desktopFiles = getDesktopFilesApi();
-    if (desktopFiles) {
+      const desktopFiles = getDesktopFilesApi();
       try {
-        const result = await desktopFiles.listDirectory(directoryPath || '', options);
-        if (!result || !Array.isArray(result.entries)) {
-          return [];
+        if (desktopFiles) {
+          const result = await desktopFiles.listDirectory(directoryPath || '', options);
+          if (!result || !Array.isArray(result.entries)) {
+            throw new FilesystemError('Directory listing returned an invalid response', {
+              reason: 'invalid-response',
+            });
+          }
+          const entries = result.entries.map<FilesystemEntry>((entry) => ({
+            name: entry.name,
+            path: normalizeFsPath(entry.path),
+            isDirectory: !!entry.isDirectory,
+            isFile: !entry.isDirectory,
+            isSymbolicLink: false,
+          }));
+          this.listDirectoryCache.set(cacheKey, {
+            entries,
+            expiresAt: Date.now() + FS_LIST_CACHE_TTL_MS,
+          });
+          return entries;
         }
-        const entries = result.entries.map<FilesystemEntry>((entry) => ({
-          name: entry.name,
-          path: normalizeFsPath(entry.path),
-          isDirectory: !!entry.isDirectory,
-          isFile: !entry.isDirectory,
-          isSymbolicLink: false,
-        }));
+
+        const params = new URLSearchParams();
+        if (directoryPath && directoryPath.trim().length > 0) {
+          params.set('path', directoryPath);
+        }
+        if (options?.respectGitignore) {
+          params.set('respectGitignore', 'true');
+        }
+        const query = params.toString();
+        const response = await runtimeFetch(`${this.baseUrl}/fs/list${query ? `?${query}` : ''}`);
+        if (!response.ok) {
+          const error = await response.json().catch(() => ({}));
+          const message = typeof error.error === 'string' ? error.error : 'Failed to list directory';
+          throw new FilesystemError(message, {
+            reason: parseFilesystemErrorReason((error as { reason?: unknown }).reason),
+            status: response.status,
+          });
+        }
+
+        const result = await response.json();
+        if (!result || !Array.isArray(result.entries)) {
+          throw new FilesystemError('Directory listing returned an invalid response', {
+            reason: 'invalid-response',
+          });
+        }
+
+        const entries = result.entries as FilesystemEntry[];
         this.listDirectoryCache.set(cacheKey, {
           entries,
           expiresAt: Date.now() + FS_LIST_CACHE_TTL_MS,
@@ -1774,39 +1810,6 @@ class OpencodeService {
         console.error('Failed to list directory contents:', error);
         throw error;
       }
-    }
-
-    try {
-      const params = new URLSearchParams();
-      if (directoryPath && directoryPath.trim().length > 0) {
-        params.set('path', directoryPath);
-      }
-      if (options?.respectGitignore) {
-        params.set('respectGitignore', 'true');
-      }
-      const query = params.toString();
-      const response = await runtimeFetch(`${this.baseUrl}/fs/list${query ? `?${query}` : ''}`);
-      if (!response.ok) {
-        const error = await response.json().catch(() => ({}));
-        const message = typeof error.error === 'string' ? error.error : 'Failed to list directory';
-        throw new Error(message);
-      }
-
-      const result = await response.json();
-      if (!result || !Array.isArray(result.entries)) {
-        return [];
-      }
-
-      const entries = result.entries as FilesystemEntry[];
-      this.listDirectoryCache.set(cacheKey, {
-        entries,
-        expiresAt: Date.now() + FS_LIST_CACHE_TTL_MS,
-      });
-      return entries;
-    } catch (error) {
-      console.error('Failed to list directory contents:', error);
-      throw error;
-    }
     })();
 
     const trackedTask = task.finally(() => {
diff --git a/packages/ui/src/sync/DOCUMENTATION.md b/packages/ui/src/sync/DOCUMENTATION.md
index 50202a71..a9b51ac9 100644
--- a/packages/ui/src/sync/DOCUMENTATION.md
+++ b/packages/ui/src/sync/DOCUMENTATION.md
@@ -75,6 +75,7 @@ The composer compares normalized attachment MIME types with the selected model's
 - A mounted directory-store consumer pins that store for its lifetime. Eviction may dispose only unmounted directories, so optimistic actions and realtime events cannot move to a replacement store while visible React consumers remain subscribed to an older identity.
 - Reconfiguration and runtime switching invalidate stale generations. A stale completion must not publish state into the new runtime.
 - Failure is recorded as `failed`; it is not converted into a successful empty snapshot. Forced demand can retry failed or completed work.
+- A failed bootstrap is classified as `os-permission` only when the owning runtime filesystem API independently confirms `EPERM`/`EACCES` for that exact directory. OpenCode/proxy error text is never used as permission evidence. The scheduler retains the directory-scoped reason so local Desktop can offer native folder selection before a forced retry.
 
 Bootstrap remains stale-while-revalidate: a directory store may paint persisted sessions immediately, but only a successful authoritative fetch may replace that cached list.
 
diff --git a/packages/ui/src/sync/child-store.test.ts b/packages/ui/src/sync/child-store.test.ts
index 64fed08f..2ee99f9b 100644
--- a/packages/ui/src/sync/child-store.test.ts
+++ b/packages/ui/src/sync/child-store.test.ts
@@ -13,6 +13,7 @@ import {
   setSyncPerformanceDiagnosticsEnabled,
 } from './performance-diagnostics';
 import { DIR_IDLE_TTL_MS } from './types';
+import { FilesystemError } from '@/lib/api/files-errors';
 
 const deferred = () => {
   let resolve!: () => void;
@@ -414,6 +415,40 @@ describe('ChildStoreManager directory bootstrap scheduler', () => {
     manager.disposeAll();
   });
 
+  test('records os-permission failures and clears them on forced retry', async () => {
+    const manager = new ChildStoreManager();
+    let denied = true;
+    const cleanup = manager.configure({
+      onBootstrap: () => {
+        if (denied) {
+          throw new FilesystemError('Access denied', { reason: 'os-permission', status: 403 });
+        }
+      },
+    });
+
+    manager.requestBootstrap({ directory: '/protected', priority: 'selected', reason: 'current-directory' });
+    await settle();
+    await settle();
+
+    expect(manager.getBootstrapState('/protected')).toBe('failed');
+    expect(manager.getBootstrapFailure('/protected')).toBe('os-permission');
+
+    denied = false;
+    manager.requestBootstrap({
+      directory: '/protected',
+      priority: 'selected',
+      reason: 'action-demand',
+      force: true,
+    });
+    await settle();
+    await settle();
+
+    expect(manager.getBootstrapState('/protected')).toBe('complete');
+    expect(manager.getBootstrapFailure('/protected')).toBe(undefined);
+    cleanup();
+    manager.disposeAll();
+  });
+
   test('continues after a synchronous bootstrap failure', async () => {
     const manager = new ChildStoreManager();
     const started: string[] = [];
diff --git a/packages/ui/src/sync/child-store.ts b/packages/ui/src/sync/child-store.ts
index f3b5b194..353b0a03 100644
--- a/packages/ui/src/sync/child-store.ts
+++ b/packages/ui/src/sync/child-store.ts
@@ -6,6 +6,7 @@ import { readDirCache, persistVcs, persistProjectMeta, persistIcon, persistSessi
 import { normalizePath } from "@/lib/pathNormalization"
 import { startSessionLoadPerformanceEvent } from "./session-load-performance"
 import { countSyncPerformance } from "./performance-diagnostics"
+import { isFilesystemError } from "@/lib/api/files-errors"
 
 export type DirectoryStore = State & {
   /** Apply a partial state update */
@@ -216,6 +217,7 @@ export type DirectoryBootstrapDemand = {
 }
 
 export type DirectoryBootstrapState = "queued" | "running" | "complete" | "failed"
+export type DirectoryBootstrapFailureReason = "os-permission" | "generic"
 
 export type DirectoryBootstrapContext = DirectoryBootstrapDemand & {
   generation: number
@@ -296,6 +298,7 @@ export class ChildStoreManager {
   private readonly bootstrapQueue = new Map<string, QueuedBootstrap>()
   private readonly runningBootstraps = new Map<string, RunningBootstrap>()
   private readonly bootstrapStates = new Map<string, DirectoryBootstrapState>()
+  private readonly bootstrapFailures = new Map<string, DirectoryBootstrapFailureReason>()
 
   private onBootstrap?: (context: DirectoryBootstrapContext) => Promise<void> | void
   private onDispose?: (directory: string) => void
@@ -479,6 +482,11 @@ export class ChildStoreManager {
     return normalizedDirectory ? this.bootstrapStates.get(normalizedDirectory) : undefined
   }
 
+  getBootstrapFailure(directory: string): DirectoryBootstrapFailureReason | undefined {
+    const normalizedDirectory = normalizePath(directory)
+    return normalizedDirectory ? this.bootstrapFailures.get(normalizedDirectory) : undefined
+  }
+
   subscribeBootstrap(listener: () => void): () => void {
     this.bootstrapSubscribers.add(listener)
     return () => this.bootstrapSubscribers.delete(listener)
@@ -530,6 +538,7 @@ export class ChildStoreManager {
       if (demand.force) running.rerunRequested = true
       return false
     }
+    this.bootstrapFailures.delete(directory)
     const existing = this.bootstrapQueue.get(directory)
     const next: QueuedBootstrap = existing
       ? {
@@ -603,14 +612,19 @@ export class ChildStoreManager {
         .then(() => {
           if (isCurrent()) {
             this.bootstrapStates.set(next.directory, "complete")
+            this.bootstrapFailures.delete(next.directory)
             finishPerformanceEvent("complete")
           } else {
             finishPerformanceEvent("stale")
           }
         })
-        .catch(() => {
+        .catch((error) => {
           if (isCurrent()) {
             this.bootstrapStates.set(next.directory, "failed")
+            this.bootstrapFailures.set(
+              next.directory,
+              isFilesystemError(error) && error.reason === "os-permission" ? "os-permission" : "generic",
+            )
             finishPerformanceEvent("error")
           } else {
             finishPerformanceEvent("stale")
@@ -658,6 +672,7 @@ export class ChildStoreManager {
     this.bootstrapQueue.delete(directory)
     this.manualBootstrapDemands.delete(directory)
     this.bootstrapStates.delete(directory)
+    this.bootstrapFailures.delete(directory)
     for (const demands of this.bootstrapDemandsByOwner.values()) demands.delete(directory)
     this.children.delete(directory)
     this.notifyRegistrySubscribers()
@@ -719,6 +734,7 @@ export class ChildStoreManager {
     this.bootstrapQueue.clear()
     this.runningBootstraps.clear()
     this.bootstrapStates.clear()
+    this.bootstrapFailures.clear()
     this.bootstrapDemandsByOwner.clear()
     this.manualBootstrapDemands.clear()
     this.notifyBootstrapSubscribers()
diff --git a/packages/ui/src/sync/sync-context.tsx b/packages/ui/src/sync/sync-context.tsx
index be956ca3..ae50c509 100644
--- a/packages/ui/src/sync/sync-context.tsx
+++ b/packages/ui/src/sync/sync-context.tsx
@@ -68,6 +68,7 @@ import { getPermissionToastKey, showPermissionNeededToast } from "./permission-t
 import { getRuntimeLiveStatusSeed, LIVE_STATUS_TTL_MS } from "./runtime-live-memory"
 import { getRuntimeKey } from "@/lib/runtime-switch"
 import { getRegisteredRuntimeAPIs } from "@/contexts/runtimeAPIRegistry"
+import { isFilesystemError } from "@/lib/api/files-errors"
 import { listGlobalSessionPages } from "@/stores/globalSessions"
 import { areRequestArraysReferentiallyEqual, collectScopedBlockingRequests } from "./scoped-blocking-requests"
 import { EMPTY_USER_MESSAGE_HISTORY_SNAPSHOT, buildUserMessageHistorySnapshot, type UserMessageHistorySnapshot } from "./user-message-history"
@@ -2068,7 +2069,21 @@ export function SyncProvider(props: {
         }
 
         const result = await runBootstrap(0)
-        if (result === "failed") throw new Error(`Directory bootstrap failed for ${directory}`)
+        if (result === "failed") {
+          // OpenCode can mask the underlying errno while initializing an
+          // inaccessible workspace. Probe the exact directory through the
+          // owning runtime filesystem API so only an authoritative local
+          // EPERM/EACCES becomes an actionable grant-access failure.
+          const files = getRegisteredRuntimeAPIs()?.files
+          if (files) {
+            try {
+              await files.listDirectory(directory)
+            } catch (error) {
+              if (isFilesystemError(error) && error.reason === "os-permission") throw error
+            }
+          }
+          throw new Error(`Directory bootstrap failed for ${directory}`)
+        }
 
         // Selecting a session whose directory this client had not indexed yet
         // routes it through the active directory as a documented guess. This is
diff --git a/packages/web/server/lib/fs/DOCUMENTATION.md b/packages/web/server/lib/fs/DOCUMENTATION.md
index 6c82a832..4629135b 100644
--- a/packages/web/server/lib/fs/DOCUMENTATION.md
+++ b/packages/web/server/lib/fs/DOCUMENTATION.md
@@ -34,5 +34,6 @@ Own filesystem API behavior for the web server runtime, including workspace-boun
 
 ## Notes for contributors
 - Keep filesystem policy (workspace root checks, error mapping, exec timeout behavior) inside this module, not in the composition root.
+- Filesystem `EPERM`/`EACCES` failures use the stable `reason: "os-permission"` response marker. Policy denials such as workspace-boundary or missing-grant failures must not use that marker because a native folder picker cannot remediate them.
 - If adding new `/api/fs/*` endpoints, add them in `routes.js` and extend this document.
 - `GET /api/fs/list` may resolve symlinks with `realpath` to read directory contents, but the response `path` and each entry `path` must stay in the caller's requested path space (`path.join(requestedPath, name)`). Returning real paths breaks file-tree expansion for directories reached through workspace symlinks.
diff --git a/packages/web/server/lib/fs/routes.js b/packages/web/server/lib/fs/routes.js
index 95887cf5..a8af1142 100644
--- a/packages/web/server/lib/fs/routes.js
+++ b/packages/web/server/lib/fs/routes.js
@@ -16,6 +16,16 @@ const pruneOutsideFileGrants = () => {
   }
 };
 
+const isOsPermissionError = (error) => (
+  error
+  && typeof error === 'object'
+  && (error.code === 'EACCES' || error.code === 'EPERM')
+);
+
+const sendOsPermissionDenied = (res, message) => (
+  res.status(403).json({ error: message, reason: 'os-permission' })
+);
+
 export const mintOutsideFileGrant = async (targetPath, {
   scopes = ['stat', 'read', 'raw'],
   fsPromises = nodeFsPromises,
@@ -583,6 +593,9 @@ export const registerFsRoutes = (app, dependencies) => {
       await fsPromises.mkdir(resolvedPath, { recursive: true });
       return res.json({ success: true, path: resolvedPath });
     } catch (error) {
+      if (isOsPermissionError(error)) {
+        return sendOsPermissionDenied(res, 'Access denied');
+      }
       console.error('Failed to create directory:', error);
       return res.status(500).json({ error: error.message || 'Failed to create directory' });
     }
@@ -746,8 +759,8 @@ export const registerFsRoutes = (app, dependencies) => {
         }
         return res.status(404).json({ error: 'File not found' });
       }
-      if (err && typeof err === 'object' && err.code === 'EACCES') {
-        return res.status(403).json({ error: 'Access to file denied' });
+      if (isOsPermissionError(err)) {
+        return sendOsPermissionDenied(res, 'Access to file denied');
       }
       console.error('Failed to stat file:', error);
       return res.status(500).json({ error: (error && error.message) || 'Failed to stat file' });
@@ -818,8 +831,8 @@ export const registerFsRoutes = (app, dependencies) => {
         }
         return res.status(404).json({ error: 'File not found' });
       }
-      if (err && typeof err === 'object' && err.code === 'EACCES') {
-        return res.status(403).json({ error: 'Access to file denied' });
+      if (isOsPermissionError(err)) {
+        return sendOsPermissionDenied(res, 'Access to file denied');
       }
       console.error('Failed to read file:', error);
       return res.status(500).json({ error: (error && error.message) || 'Failed to read file' });
@@ -903,8 +916,8 @@ export const registerFsRoutes = (app, dependencies) => {
       if (err && typeof err === 'object' && err.code === 'ENOENT') {
         return res.status(404).json({ error: 'File not found' });
       }
-      if (err && typeof err === 'object' && err.code === 'EACCES') {
-        return res.status(403).json({ error: 'Access to file denied' });
+      if (isOsPermissionError(err)) {
+        return sendOsPermissionDenied(res, 'Access to file denied');
       }
       console.error('Failed to read raw file:', error);
       return res.status(500).json({ error: (error && error.message) || 'Failed to read file' });
@@ -964,8 +977,8 @@ export const registerFsRoutes = (app, dependencies) => {
       if (err && typeof err === 'object' && err.code === 'ENOENT') {
         return res.status(404).json({ error: 'File not found' });
       }
-      if (err && typeof err === 'object' && err.code === 'EACCES') {
-        return res.status(403).json({ error: 'Access to file denied' });
+      if (isOsPermissionError(err)) {
+        return sendOsPermissionDenied(res, 'Access to file denied');
       }
       console.error('Failed to serve file:', error);
       return res.status(500).json({ error: (error && error.message) || 'Failed to serve file' });
@@ -1026,8 +1039,8 @@ export const registerFsRoutes = (app, dependencies) => {
       return res.json({ success: true, path: resolved.resolved });
     } catch (error) {
       const err = error;
-      if (err && typeof err === 'object' && err.code === 'EACCES') {
-        return res.status(403).json({ error: 'Access denied' });
+      if (isOsPermissionError(err)) {
+        return sendOsPermissionDenied(res, 'Access denied');
       }
       console.error('Failed to write file:', error);
       return res.status(500).json({ error: (error && error.message) || 'Failed to write file' });
@@ -1061,8 +1074,8 @@ export const registerFsRoutes = (app, dependencies) => {
       if (err && typeof err === 'object' && err.code === 'ENOENT') {
         return res.status(404).json({ error: 'File or directory not found' });
       }
-      if (err && typeof err === 'object' && err.code === 'EACCES') {
-        return res.status(403).json({ error: 'Access denied' });
+      if (isOsPermissionError(err)) {
+        return sendOsPermissionDenied(res, 'Access denied');
       }
       console.error('Failed to delete path:', error);
       return res.status(500).json({ error: (error && error.message) || 'Failed to delete path' });
@@ -1116,8 +1129,8 @@ export const registerFsRoutes = (app, dependencies) => {
       if (err && typeof err === 'object' && err.code === 'ENOENT') {
         return res.status(404).json({ error: 'Source path not found' });
       }
-      if (err && typeof err === 'object' && err.code === 'EACCES') {
-        return res.status(403).json({ error: 'Access denied' });
+      if (isOsPermissionError(err)) {
+        return sendOsPermissionDenied(res, 'Access denied');
       }
       console.error('Failed to rename path:', error);
       return res.status(500).json({ error: (error && error.message) || 'Failed to rename path' });
@@ -1173,6 +1186,9 @@ export const registerFsRoutes = (app, dependencies) => {
       if (err && typeof err === 'object' && err.code === 'ENOENT') {
         return res.status(404).json({ error: 'Path not found' });
       }
+      if (isOsPermissionError(err)) {
+        return sendOsPermissionDenied(res, 'Access to path denied');
+      }
       console.error('Failed to reveal path:', error);
       return res.status(500).json({ error: (error && error.message) || 'Failed to reveal path' });
     }
@@ -1315,7 +1331,7 @@ export const registerFsRoutes = (app, dependencies) => {
 
       const stats = await fsPromises.stat(resolvedPath);
       if (!stats.isDirectory()) {
-        return res.status(400).json({ error: 'Specified path is not a directory' });
+        return res.status(400).json({ error: 'Specified path is not a directory', reason: 'not-directory' });
       }
 
       const dirents = await fsPromises.readdir(resolvedPath, { withFileTypes: true });
@@ -1416,10 +1432,10 @@ export const registerFsRoutes = (app, dependencies) => {
         if (isPlansPath) {
           return res.json({ path: requestedPath || resolvedPath || rawPath, entries: [] });
         }
-        return res.status(404).json({ error: 'Directory not found' });
+        return res.status(404).json({ error: 'Directory not found', reason: 'not-found' });
       }
-      if (code === 'EACCES') {
-        return res.status(403).json({ error: 'Access to directory denied' });
+      if (isOsPermissionError(err)) {
+        return sendOsPermissionDenied(res, 'Access to directory denied');
       }
       return res.status(500).json({ error: (error && error.message) || 'Failed to list directory' });
     }
diff --git a/packages/web/server/lib/fs/routes.test.js b/packages/web/server/lib/fs/routes.test.js
index 576c0964..be4b1022 100644
--- a/packages/web/server/lib/fs/routes.test.js
+++ b/packages/web/server/lib/fs/routes.test.js
@@ -709,4 +709,19 @@ describe('fs list symlink path space (issue 2627)', () => {
     ]);
     expect(fsPromises.readdir).toHaveBeenCalledWith('/real/pkg', { withFileTypes: true });
   });
+
+  for (const code of ['EACCES', 'EPERM']) {
+    it(`maps ${code} to the os-permission contract`, async () => {
+      const error = Object.assign(new Error('denied'), { code });
+      const handler = registerList({
+        stat: vi.fn(async () => ({ isDirectory: () => true })),
+        readdir: vi.fn(async () => { throw error; }),
+      });
+
+      const res = await callList(handler, { path: '/workspace/protected' });
+
+      expect(res.statusCode).toBe(403);
+      expect(res.body).toEqual({ error: 'Access to directory denied', reason: 'os-permission' });
+    });
+  }
 });
diff --git a/packages/web/src/api/files.test.ts b/packages/web/src/api/files.test.ts
index 3587da99..19bd5bb3 100644
--- a/packages/web/src/api/files.test.ts
+++ b/packages/web/src/api/files.test.ts
@@ -25,6 +25,34 @@ const urls: RuntimeUrlResolver = {
 };
 
 describe('createWebFilesAPI', () => {
+  it('preserves the directory permission failure contract', async () => {
+    const { createWebFilesAPI } = await import('./files');
+    const api = createWebFilesAPI({ urls, getDirectory: () => '/workspace' });
+    runtimeFetchMock.mockResolvedValueOnce(Response.json(
+      { error: 'Access to directory denied', reason: 'os-permission' },
+      { status: 403 },
+    ));
+
+    const error = await api.listDirectory('/protected').catch((caught) => caught);
+
+    expect(error).toMatchObject({
+      name: 'FilesystemError',
+      reason: 'os-permission',
+      status: 403,
+      message: 'Access to directory denied',
+    });
+  });
+
+  it('rejects malformed successful directory listings', async () => {
+    const { createWebFilesAPI } = await import('./files');
+    const api = createWebFilesAPI({ urls, getDirectory: () => '/workspace' });
+    runtimeFetchMock.mockResolvedValueOnce(Response.json({ path: '/workspace' }));
+
+    await expect(api.listDirectory('/workspace')).rejects.toMatchObject({
+      reason: 'invalid-response',
+    });
+  });
+
   it('uses per-call workspace directory for stat and read requests', async () => {
     const { createWebFilesAPI } = await import('./files');
     const api = createWebFilesAPI({ urls, getDirectory: () => '/stale-workspace' });
diff --git a/packages/web/src/api/files.ts b/packages/web/src/api/files.ts
index 6b62967c..3d1c91ae 100644
--- a/packages/web/src/api/files.ts
+++ b/packages/web/src/api/files.ts
@@ -4,6 +4,10 @@ import type {
   FileSearchResult,
   FilesAPI,
 } from '@openchamber/ui/lib/api/types';
+import {
+  FilesystemError,
+  parseFilesystemErrorReason,
+} from '@openchamber/ui/lib/api/files-errors';
 import { runtimeFetch } from '@openchamber/ui/lib/runtime-fetch';
 
 const normalizePath = (path: string): string => path.replace(/\\/g, '/');
@@ -28,12 +32,16 @@ type WebDirectoryListResponse = {
 };
 
 const toDirectoryListResult = (fallbackDirectory: string, payload: WebDirectoryListResponse): DirectoryListResult => {
+  if (!payload || !Array.isArray(payload.entries)) {
+    throw new FilesystemError('Directory listing returned an invalid response', {
+      reason: 'invalid-response',
+    });
+  }
   const directory = normalizePath(payload?.directory || payload?.path || fallbackDirectory);
-  const entries = Array.isArray(payload?.entries) ? payload.entries : [];
 
   return {
     directory,
-    entries: entries
+    entries: payload.entries
       .filter((entry): entry is Required<Pick<WebDirectoryEntry, 'name' | 'path'>> & { isDirectory?: boolean } =>
         Boolean(entry && typeof entry.name === 'string' && typeof entry.path === 'string')
       )
@@ -67,8 +75,17 @@ export const createWebFilesAPI = ({ getDirectory }: WebFilesAPIOptions): FilesAP
     });
 
     if (!response.ok) {
-      const error = await response.json().catch(() => ({ error: response.statusText }));
-      throw new Error((error as { error?: string }).error || 'Failed to list directory');
+      const error = await response.json().catch(() => ({ error: response.statusText })) as {
+        error?: string;
+        reason?: unknown;
+      };
+      throw new FilesystemError(
+        error.error || 'Failed to list directory',
+        {
+          reason: parseFilesystemErrorReason(error.reason),
+          status: response.status,
+        },
+      );
     }
 
     const result = (await response.json()) as WebDirectoryListResponse;
diff --git a/packages/web/vitest.config.ts b/packages/web/vitest.config.ts
index 275cd22f..599b01a2 100644
--- a/packages/web/vitest.config.ts
+++ b/packages/web/vitest.config.ts
@@ -5,6 +5,7 @@ export default defineConfig({
   resolve: {
     alias: {
       'bun:test': fileURLToPath(new URL('./test/bun-test-shim.ts', import.meta.url)),
+      '@openchamber/ui': fileURLToPath(new URL('../ui/src', import.meta.url)),
     },
   },
 });

From f5603153dfffc29b06a0616b3695f621c726d6a2 Mon Sep 17 00:00:00 2001
From: deatheros <12375795+deatheros@users.noreply.github.com>
Date: Fri, 7 Aug 2026 02:29:27 +0300
Subject: [PATCH 52/57] fix(ui): use readable permission error color

---
 packages/ui/src/components/session/DirectoryExplorerDialog.tsx  | 2 +-
 .../ui/src/components/session/sidebar/SessionGroupSection.tsx   | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/ui/src/components/session/DirectoryExplorerDialog.tsx b/packages/ui/src/components/session/DirectoryExplorerDialog.tsx
index ba9d7bb6..c5274f08 100644
--- a/packages/ui/src/components/session/DirectoryExplorerDialog.tsx
+++ b/packages/ui/src/components/session/DirectoryExplorerDialog.tsx
@@ -616,7 +616,7 @@ export const DirectoryExplorerDialog: React.FC<DirectoryExplorerDialogProps> = (
           </div>
         ) : browseErrorReason && browseErrorReason !== 'not-found' ? (
           <div className="flex flex-col items-center gap-3 px-4 py-10 text-center">
-            <div className="typography-ui-label text-[var(--status-error-foreground)]">
+            <div className="typography-ui-label text-status-error">
               {browseErrorReason === 'os-permission'
                 ? t('directoryExplorerDialog.browse.permissionDenied')
                 : t('directoryExplorerDialog.browse.loadFailed')}
diff --git a/packages/ui/src/components/session/sidebar/SessionGroupSection.tsx b/packages/ui/src/components/session/sidebar/SessionGroupSection.tsx
index 1a7e7304..a4405a0b 100644
--- a/packages/ui/src/components/session/sidebar/SessionGroupSection.tsx
+++ b/packages/ui/src/components/session/sidebar/SessionGroupSection.tsx
@@ -1052,7 +1052,7 @@ function SessionGroupSectionBase(props: Props): React.ReactNode {
         </div>
       ) : null}
       {totalSessions > 0 && bootstrapFailureNotice ? (
-        <div className="py-1 pl-[26px] text-left typography-micro text-[var(--status-error-foreground)]">
+        <div className="py-1 pl-[26px] text-left typography-micro text-status-error">
           {bootstrapFailureNotice}
         </div>
       ) : null}

From 0ff630c2970b3417ae507c0000c3f0f7d729938e Mon Sep 17 00:00:00 2001
From: Bohdan Triapitsyn <artmore@protonmail.com>
Date: Fri, 7 Aug 2026 08:41:30 +0300
Subject: [PATCH 53/57] fix(ui): repair sync test contracts

---
 .../sync/__tests__/session-switch-resync.test.ts  | 15 ++++++++-------
 packages/ui/src/sync/input-store.test.ts          |  2 +-
 2 files changed, 9 insertions(+), 8 deletions(-)

diff --git a/packages/ui/src/sync/__tests__/session-switch-resync.test.ts b/packages/ui/src/sync/__tests__/session-switch-resync.test.ts
index cd7ecd27..5c860956 100644
--- a/packages/ui/src/sync/__tests__/session-switch-resync.test.ts
+++ b/packages/ui/src/sync/__tests__/session-switch-resync.test.ts
@@ -4,7 +4,7 @@ import type { Event, PermissionRequest, QuestionRequest } from "@opencode-ai/sdk
 
 const listPendingQuestionsCalls: Array<{ directories?: Array<string | null | undefined> }> = []
 const listPendingPermissionsCalls: Array<{ directories?: Array<string | null | undefined> }> = []
-const todoPersistWrites: Array<{ sessionID: string; todos: unknown }> = []
+const todoPersistWrites: Array<{ directory: string; sessionID: string; todos: unknown }> = []
 let pendingQuestionsResponse: QuestionRequest[] = []
 let pendingPermissionsResponse: PermissionRequest[] = []
 let pendingQuestionsShouldThrow = false
@@ -44,8 +44,8 @@ mock.module("@/stores/useConfigStore", () => ({
 mock.module("@/stores/useTodosPersistStore", () => ({
   useTodosPersistStore: {
     getState: () => ({
-      setSessionTodos: (sessionID: string, todos: unknown) => {
-        todoPersistWrites.push({ sessionID, todos })
+      setSessionTodos: (directory: string, sessionID: string, todos: unknown) => {
+        todoPersistWrites.push({ directory, sessionID, todos })
       },
     }),
   },
@@ -66,6 +66,7 @@ mock.module("@/components/ui", () => ({
 
 import { INITIAL_STATE, type State } from "../types"
 import { ChildStoreManager, type DirectoryStore } from "../child-store"
+import { getRuntimeKey } from "@/lib/runtime-switch"
 const {
   createEventRoutingIndex,
   handleEvent,
@@ -257,10 +258,10 @@ describe("resyncBlockingRequestsForDirectory", () => {
       storeWrites += 1
     })
     setActiveSession("/target", "ses_a")
-    handleEvent("global", event, childStores, routingIndex)
+    handleEvent("global", event, childStores, routingIndex, getRuntimeKey())
 
     expect(store.getState().todo.ses_a).toEqual(todos)
-    expect(todoPersistWrites).toEqual([{ sessionID: "ses_a", todos }])
+    expect(todoPersistWrites).toEqual([{ directory: "/target", sessionID: "ses_a", todos }])
     expect(storeWrites).toBe(1)
 
     const stateAfterFirstSnapshot = store.getState()
@@ -272,10 +273,10 @@ describe("resyncBlockingRequestsForDirectory", () => {
     expect(duplicateTodos).not.toBe(todos)
     expect(duplicateTodos).toEqual(todos)
 
-    handleEvent("global", duplicateEvent, childStores, routingIndex)
+    handleEvent("global", duplicateEvent, childStores, routingIndex, getRuntimeKey())
 
     expect(store.getState()).toBe(stateAfterFirstSnapshot)
-    expect(todoPersistWrites).toEqual([{ sessionID: "ses_a", todos }])
+    expect(todoPersistWrites).toEqual([{ directory: "/target", sessionID: "ses_a", todos }])
     expect(storeWrites).toBe(1)
     unsubscribe()
     childStores.disposeAll()
diff --git a/packages/ui/src/sync/input-store.test.ts b/packages/ui/src/sync/input-store.test.ts
index 33880228..5303c2d5 100644
--- a/packages/ui/src/sync/input-store.test.ts
+++ b/packages/ui/src/sync/input-store.test.ts
@@ -339,7 +339,7 @@ describe("input-store attachments", () => {
     expect(await addPromise).toBe(true)
     const files = useInputStore.getState().attachedFiles
     expect(files).toHaveLength(1)
-    expect(files[0].sourceDocumentId).toBeUndefined()
+    expect(files[0].sourceDocumentId).toBe(undefined)
 
     useInputStore.getState().removeAttachedFile(files[0].id)
     expect(useInputStore.getState().attachedFiles).toEqual([])

From bc380e6e1b12d87d337a72c80a9a0333875bfd53 Mon Sep 17 00:00:00 2001
From: Serhii Dziupin <serkraser@gmail.com>
Date: Fri, 7 Aug 2026 09:01:31 +0300
Subject: [PATCH 54/57] perf: cut cold-start download 58% and startup heap 22%
 via measured chunk-graph fixes (#2742)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(ui): update session-switch-resync test to current handleEvent/setSessionTodos signatures

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>

* perf(build): split Shiki grammars/themes, CodeMirror legacy modes, and @pierre/diffs into on-demand chunks

Merging @shikijs/langs into one manual vendor chunk made the first language
request download every grammar (7.4 MB raw / 1 MB gzip). Letting Rollup split
these packages per dynamically imported module downloads only the languages,
themes, and modes actually used — matching how the worker build already
behaves. @pierre/diffs is split the same way so its pure patch parser (used by
the eager tool renderer) no longer drags the Shiki-importing render stack into
the startup graph.

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>

* perf(ui): restore lazy heavy views and stop eager settings-graph loading

- MainLayout: DiffView/FilesView/GitView/PlanView return to lazyWithChunkRecovery
  (they were silently made static in 2031e3b4 while their Suspense wrappers
  remained), keeping the CodeMirror and @pierre/diffs stacks out of startup.
- ContextPanel: same lazy treatment for its Diff/Files/Git/Plan/Walkthrough
  tabs, with null Suspense fallbacks.
- CommandPalette imported getSettingsNavIcon from SettingsView, statically
  pulling the entire settings surface (SkillsPage -> CodeMirrorEditor -> vim
  mode, theme registry -> @pierre/diffs) into the eager graph; the helper now
  lives in lib/settings/metadata.
- The windowed SettingsWindow mounts only after its first open: rendering the
  lazy component closed made React fetch the SettingsView chunk graph at
  startup.

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>

* perf(ui): keep @pierre/diffs + Shiki out of the eager chat graph and defer diff worker warmup

- DiffWorkerProvider no longer statically imports @pierre/diffs/worker or the
  theme registry, and no longer spawns 3 workers plus a main-thread shared
  highlighter during mount. Pools are created on demand through a dynamic
  module load, warmed via requestIdleCallback after startup settles, and
  useWorkerPool notifies consumers when a pool becomes available.
- ToolPart's rich diff preview moves to lazily loaded ToolPartDiffPreview;
  the plain-text patch (PlainDiffFallback) renders while the chunk loads,
  mirroring the existing error fallback. Theme registration happens during
  render inside the lazy module so PatchDiff never renders unregistered ids.
- ChatInput mounts its lazy ToolOutputDialog only after the first attachment
  preview opens instead of fetching the dialog chunk on the draft screen.
- getMarkdownSyntaxVars moves to a pierre-free markdownSyntaxVars module so
  eager code-rendering consumers stop importing the registration module.

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>

* perf(web): load ghostty-web and Nerd Fonts on first terminal use

- ghostty-web (638 KB raw JS + WASM VT) is dynamically imported when a
  terminal actually mounts; TerminalView stays eagerly importable for the
  bottom dock.
- The ~2 MB of CDN Nerd Fonts are no longer preloaded and force-loaded on
  every cold start. index.html exposes an idempotent
  __openchamberEnsureNerdFonts hook; TerminalViewport requests it on mount
  and waits up to 2s so a cached font is in place before the glyph atlas is
  built, while a cold CDN fetch never blocks the terminal. Runtimes without
  the hook (VS Code, mobile) resolve immediately, matching their existing
  fallback-font behavior.

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>

---------

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>
---
 packages/ui/src/components/chat/ChatInput.tsx |  29 ++-
 .../ui/src/components/chat/DiffPreview.tsx    |   2 +-
 .../components/chat/MarkdownRendererImpl.tsx  |   3 +-
 .../chat/markdown/markdownSyntaxVars.ts       |  31 +++
 .../components/chat/markdown/markdownTheme.ts |  27 ---
 .../chat/message/parts/DOCUMENTATION.md       |   3 +-
 .../chat/message/parts/PlainDiffFallback.tsx  |  19 ++
 .../chat/message/parts/ToolPart.tsx           | 156 +------------
 .../message/parts/ToolPartDiffPreview.tsx     | 140 ++++++++++++
 .../message/parts/VirtualizedCodeBlock.tsx    |   2 +-
 .../components/code/WorkerHighlightedCode.tsx |   2 +-
 .../ui/src/components/layout/ContextPanel.tsx |  47 ++--
 .../ui/src/components/layout/MainLayout.tsx   |  37 +++-
 .../components/terminal/TerminalViewport.tsx  |  37 +++-
 .../ui/src/components/ui/CommandPalette.tsx   |   2 +-
 .../ui/src/components/views/SettingsView.tsx  |  62 +-----
 .../ui/src/contexts/DiffWorkerProvider.tsx    | 205 +++++++++++-------
 packages/ui/src/lib/settings/metadata.ts      |  63 ++++++
 packages/web/index.html                       |  54 ++---
 packages/web/vite.config.ts                   |  22 ++
 vite.config.ts                                |  22 ++
 21 files changed, 585 insertions(+), 380 deletions(-)
 create mode 100644 packages/ui/src/components/chat/markdown/markdownSyntaxVars.ts
 create mode 100644 packages/ui/src/components/chat/message/parts/PlainDiffFallback.tsx
 create mode 100644 packages/ui/src/components/chat/message/parts/ToolPartDiffPreview.tsx

diff --git a/packages/ui/src/components/chat/ChatInput.tsx b/packages/ui/src/components/chat/ChatInput.tsx
index 38871269..9e055d41 100644
--- a/packages/ui/src/components/chat/ChatInput.tsx
+++ b/packages/ui/src/components/chat/ChatInput.tsx
@@ -32,7 +32,7 @@ import {
 } from '@/lib/chatDraftPersistence';
 import { ReviewFlowDialog, type ReviewFlowExecution } from '@/components/session/ReviewFlowDialog';
 import { AttachedFilesList, AttachedVSCodeFileChips, ActiveEditorFileSuggestion } from './FileAttachment';
-import ToolOutputDialog from './message/ToolOutputDialog';
+import { lazyWithChunkRecovery } from '@/lib/chunkLoadRecovery';
 import type { ToolPopupContent } from './message/types';
 import { QueuedMessageChips } from './QueuedMessageChips';
 import { AutoReviewBanner } from './AutoReviewBanner';
@@ -142,6 +142,10 @@ import { RevertedMessageDock } from './composer/ui/RevertedMessageDock';
 import { SessionSuggestionChip } from '@/components/chat/SessionSuggestionChip';
 import { SessionGoalRow } from '@/components/chat/SessionGoalRow';
 
+// Lazy like in ChatMessage: a static import would pull the @pierre/diffs and
+// Shiki stacks into the eager startup graph for a dialog opened on demand.
+const ToolOutputDialog = lazyWithChunkRecovery(() => import('./message/ToolOutputDialog'));
+
 const MAX_VISIBLE_COMPOSER_LINES = 8;
 /**
  * Mobile grows the composer with content instead of offering a fullscreen
@@ -383,6 +387,15 @@ const ChatInputComponent: React.FC<ChatInputProps> = ({ onOpenSettings, scrollTo
         title: '',
         content: '',
     });
+    // Mount the lazy preview dialog only after its first open; rendering it
+    // closed would fetch the ToolOutputDialog chunk (with the @pierre/diffs
+    // stack) on the draft screen before any preview is requested.
+    const [attachmentPreviewMounted, setAttachmentPreviewMounted] = React.useState(false);
+    React.useEffect(() => {
+        if (attachmentPreview.open) {
+            setAttachmentPreviewMounted(true);
+        }
+    }, [attachmentPreview.open]);
     const attachmentCompatibilityRef = React.useRef({
         modelKey: `${currentProviderId ?? ''}/${currentModelId ?? ''}`,
         modalitySignature: currentModelMetadata?.modalities?.input?.slice().sort().join(',') ?? null,
@@ -2786,11 +2799,15 @@ const ChatInputComponent: React.FC<ChatInputProps> = ({ onOpenSettings, scrollTo
             submitting={reviewFlowSubmitting}
             onConfirm={handleStartReviewFlow}
         />
-        <ToolOutputDialog
-            popup={attachmentPreview}
-            onOpenChange={handleAttachmentPreviewOpenChange}
-            isMobile={isMobile}
-        />
+        {attachmentPreviewMounted ? (
+            <React.Suspense fallback={null}>
+                <ToolOutputDialog
+                    popup={attachmentPreview}
+                    onOpenChange={handleAttachmentPreviewOpenChange}
+                    isMobile={isMobile}
+                />
+            </React.Suspense>
+        ) : null}
 
         {/* Single always-mounted picker input. It must NOT live inside
             ComposerAttachmentControls: that component mounts once per composer
diff --git a/packages/ui/src/components/chat/DiffPreview.tsx b/packages/ui/src/components/chat/DiffPreview.tsx
index 295475c4..c749b033 100644
--- a/packages/ui/src/components/chat/DiffPreview.tsx
+++ b/packages/ui/src/components/chat/DiffPreview.tsx
@@ -2,7 +2,7 @@ import React from 'react';
 import { cn } from '@/lib/utils';
 import { getLanguageFromExtension } from '@/lib/toolHelpers';
 import { useThemeSystem } from '@/contexts/useThemeSystem';
-import { getMarkdownSyntaxVars } from '@/components/chat/markdown/markdownTheme';
+import { getMarkdownSyntaxVars } from '@/components/chat/markdown/markdownSyntaxVars';
 import { useWorkerHighlightedLines } from '@/components/code/useWorkerHighlightedLines';
 import { parseDiffToUnified } from './message/toolRenderers';
 
diff --git a/packages/ui/src/components/chat/MarkdownRendererImpl.tsx b/packages/ui/src/components/chat/MarkdownRendererImpl.tsx
index 64d0d1b5..0a8bef4c 100644
--- a/packages/ui/src/components/chat/MarkdownRendererImpl.tsx
+++ b/packages/ui/src/components/chat/MarkdownRendererImpl.tsx
@@ -20,7 +20,8 @@ import { isMobileSurfaceRuntime } from '@/lib/runtimeSurface';
 import { ensureOutsideFileGrantForDesktop } from '@/lib/outsideFileGrants';
 import { getDirectoryForFilePath, isFilePathWithinDirectory, toAbsoluteFilePath } from '@/lib/path-utils';
 import { renderMarkdownBlocks, renderMarkdownSync } from './markdown/markdownCore';
-import { ensureMarkdownShikiTheme, getMarkdownSyntaxVars } from './markdown/markdownTheme';
+import { ensureMarkdownShikiTheme } from './markdown/markdownTheme';
+import { getMarkdownSyntaxVars } from './markdown/markdownSyntaxVars';
 import {
   attachMarkdownInteractions,
   applyMarkdownCodeBlockWrapState,
diff --git a/packages/ui/src/components/chat/markdown/markdownSyntaxVars.ts b/packages/ui/src/components/chat/markdown/markdownSyntaxVars.ts
new file mode 100644
index 00000000..19de389a
--- /dev/null
+++ b/packages/ui/src/components/chat/markdown/markdownSyntaxVars.ts
@@ -0,0 +1,31 @@
+import type { Theme } from '@/types/theme';
+
+/**
+ * Build the `--md-syntax-*` CSS custom properties for the given app theme.
+ * Apply the result as inline styles on the markdown container so the static
+ * Shiki theme resolves to the active palette.
+ *
+ * Lives apart from `markdownTheme.ts` because that module imports
+ * `@pierre/diffs` for theme registration; eager consumers of these CSS vars
+ * (tool output, code blocks) must not pull that stack into the startup graph.
+ */
+export const getMarkdownSyntaxVars = (theme: Theme): Record<string, string> => {
+  const base = theme.colors.syntax.base;
+  const tokens = theme.colors.syntax.tokens ?? {};
+  const status = theme.colors.status;
+
+  return {
+    '--md-syntax-foreground': base.foreground,
+    '--md-syntax-comment': base.comment,
+    '--md-syntax-string': base.string,
+    '--md-syntax-number': base.number,
+    '--md-syntax-keyword': base.keyword,
+    '--md-syntax-operator': base.operator,
+    '--md-syntax-function': base.function,
+    '--md-syntax-type': base.type,
+    '--md-syntax-variable': base.variable,
+    '--md-syntax-property': tokens.variableProperty ?? base.variable,
+    '--md-syntax-inserted': status.success,
+    '--md-syntax-deleted': status.error,
+  };
+};
diff --git a/packages/ui/src/components/chat/markdown/markdownTheme.ts b/packages/ui/src/components/chat/markdown/markdownTheme.ts
index 30044c8e..1b40d5d1 100644
--- a/packages/ui/src/components/chat/markdown/markdownTheme.ts
+++ b/packages/ui/src/components/chat/markdown/markdownTheme.ts
@@ -1,5 +1,4 @@
 import { registerCustomTheme, type ThemeRegistrationResolved } from '@pierre/diffs';
-import type { Theme } from '@/types/theme';
 import { MARKDOWN_SHIKI_THEME, MARKDOWN_SHIKI_THEME_DEFINITION } from './markdownShikiThemeDefinition';
 
 // The static Shiki theme name. Its definition (token colors referencing
@@ -27,29 +26,3 @@ export const ensureMarkdownShikiTheme = (): void => {
     Promise.resolve(MARKDOWN_SHIKI_THEME_DEFINITION as unknown as ThemeRegistrationResolved),
   );
 };
-
-/**
- * Build the `--md-syntax-*` CSS custom properties for the given app theme.
- * Apply the result as inline styles on the markdown container so the static
- * Shiki theme resolves to the active palette.
- */
-export const getMarkdownSyntaxVars = (theme: Theme): Record<string, string> => {
-  const base = theme.colors.syntax.base;
-  const tokens = theme.colors.syntax.tokens ?? {};
-  const status = theme.colors.status;
-
-  return {
-    '--md-syntax-foreground': base.foreground,
-    '--md-syntax-comment': base.comment,
-    '--md-syntax-string': base.string,
-    '--md-syntax-number': base.number,
-    '--md-syntax-keyword': base.keyword,
-    '--md-syntax-operator': base.operator,
-    '--md-syntax-function': base.function,
-    '--md-syntax-type': base.type,
-    '--md-syntax-variable': base.variable,
-    '--md-syntax-property': tokens.variableProperty ?? base.variable,
-    '--md-syntax-inserted': status.success,
-    '--md-syntax-deleted': status.error,
-  };
-};
diff --git a/packages/ui/src/components/chat/message/parts/DOCUMENTATION.md b/packages/ui/src/components/chat/message/parts/DOCUMENTATION.md
index 466942f3..d28450ea 100644
--- a/packages/ui/src/components/chat/message/parts/DOCUMENTATION.md
+++ b/packages/ui/src/components/chat/message/parts/DOCUMENTATION.md
@@ -59,6 +59,7 @@ Use this doc when you ask an agent to change tool/header/description behavior.
 - Every other tool, including search/fetch, OpenCode built-ins, custom tools, plugins, and MCP tools, is **expandable** and renders through `ToolPart`.
 - The managed `openchamber` plugin tool uses the expandable path and hides its broad protocol input. The plugin supplies the selected action's human description as the native tool title; the UI renders that metadata without owning an action map. The full versioned result envelope renders through the same neutral JSON summary/tree/raw views as other tools, without a tool-specific output card.
 - `ToolPart` defers expanded content after a user toggle, preventing large tool input/output payloads from mounting during the initial chat render.
+- The rich tool diff preview lives in `ToolPartDiffPreview.tsx` and is lazy-loaded from `ToolPart`. It is the only tool-card piece that imports the `@pierre/diffs` + Shiki rendering stack, keeping that stack out of the eager chat startup graph. While its chunk loads (first rendered diff only) the plain-text patch from `PlainDiffFallback.tsx` renders as the Suspense fallback, mirroring the preview's error fallback. `ToolPart` itself must not statically import `@pierre/diffs` runtime modules or `@/lib/shiki/appThemeRegistry`.
 - Running bash output falls back to `state.metadata.output` until canonical `state.output` arrives. Its fixed-height output viewport follows new output until the user scrolls up, then resumes following when the user returns to the bottom. Live output appends or replaces rewritten snapshots as plain text without worker highlighting; finalized output normalizes ANSI terminal controls with a bounded synthetic-cell budget, bypasses the throttle, and receives the normal one-time highlighted rendering.
 - Thinking/Justification duration is hidden in `sorted` mode (handled in `ReasoningPart.tsx` + `JustificationBlock.tsx`).
 
@@ -93,7 +94,7 @@ Why: only navigation tools use the compact static path; all other tools need obs
 ## Quick map of files in this folder
 
 - Text: `AssistantTextPart.tsx`, `UserTextPart.tsx`
-- Tools: `ToolPart.tsx`, `ProgressiveGroup.tsx`, `toolPresentation.tsx`, `toolRenderUtils.ts`, `ToolRevealOnMount.tsx`
+- Tools: `ToolPart.tsx`, `ToolPartDiffPreview.tsx`, `PlainDiffFallback.tsx`, `ProgressiveGroup.tsx`, `toolPresentation.tsx`, `toolRenderUtils.ts`, `ToolRevealOnMount.tsx`
 - Reasoning/justification: `ReasoningPart.tsx`, `JustificationBlock.tsx`
 - Status/placeholders: `WorkingPlaceholder.tsx`, `SessionActiveSpinner.tsx`, `MigratingPart.tsx`, `BusyDots.tsx`
 - Utility renderers: `VirtualizedCodeBlock.tsx`, `MinDurationShineText.tsx`
diff --git a/packages/ui/src/components/chat/message/parts/PlainDiffFallback.tsx b/packages/ui/src/components/chat/message/parts/PlainDiffFallback.tsx
new file mode 100644
index 00000000..6e6e91e8
--- /dev/null
+++ b/packages/ui/src/components/chat/message/parts/PlainDiffFallback.tsx
@@ -0,0 +1,19 @@
+import React from 'react';
+
+/**
+ * Plain-text patch rendering used when the rich `@pierre/diffs` preview is
+ * unavailable: non-diff render modes, preview errors, and while the lazily
+ * loaded diff preview chunk is still downloading. Lives in its own module so
+ * `ToolPart` can render it without importing the @pierre/diffs stack.
+ */
+export const PlainDiffFallback: React.FC<{ diff: string }> = ({ diff }) => (
+    <pre
+        className="m-0 overflow-auto whitespace-pre-wrap break-words rounded-lg p-2 typography-code"
+        style={{
+            backgroundColor: 'var(--syntax-base-background)',
+            color: 'var(--syntax-base-foreground)',
+        }}
+    >
+        {diff}
+    </pre>
+);
diff --git a/packages/ui/src/components/chat/message/parts/ToolPart.tsx b/packages/ui/src/components/chat/message/parts/ToolPart.tsx
index 2969dd85..c5a2e4a3 100644
--- a/packages/ui/src/components/chat/message/parts/ToolPart.tsx
+++ b/packages/ui/src/components/chat/message/parts/ToolPart.tsx
@@ -2,7 +2,6 @@
 import React from 'react';
 import { useMobileAppActions } from '@/apps/mobileAppContext';
 import { RuntimeAPIContext } from '@/contexts/runtimeAPIContext';
-import { PatchDiff } from '@pierre/diffs/react';
 import { cn } from '@/lib/utils';
 import { SimpleMarkdownRenderer } from '../../MarkdownRenderer';
 import { MessageFilesDisplay } from '../../FileAttachment';
@@ -10,7 +9,6 @@ import { getToolMetadata } from '@/lib/toolHelpers';
 import type { ToolPart as ToolPartType, ToolState as ToolStateUnion, FilePart } from '@opencode-ai/sdk/v2';
 import { toolDisplayStyles } from '@/lib/typography';
 import { WorkerHighlightedCode } from '@/components/code/WorkerHighlightedCode';
-import { useOptionalThemeSystem } from '@/contexts/useThemeSystem';
 import { useEffectiveDirectory } from '@/hooks/useEffectiveDirectory';
 import { useSessionUIStore } from '@/sync/session-ui-store';
 import { useSessionMessageRecords, useEnsureSessionMessages } from '@/sync/sync-context';
@@ -24,8 +22,8 @@ import { FileTypeIcon } from '@/components/icons/FileTypeIcon';
 import { copyTextToClipboard } from '@/lib/clipboard';
 import type { ContentChangeReason } from '@/hooks/useChatAutoFollow';
 import type { ToolPopupContent } from '../types';
-import { ensurePierreThemeRegistered } from '@/lib/shiki/appThemeRegistry';
-import { getDefaultTheme } from '@/lib/theme/themes';
+import { PlainDiffFallback } from './PlainDiffFallback';
+import { lazyWithChunkRecovery } from '@/lib/chunkLoadRecovery';
 
 import {
     formatEditOutput,
@@ -385,40 +383,6 @@ const getToolDiagnosticSection = (
     };
 };
 
-const usePierreThemeConfig = () => {
-    const themeSystem = useOptionalThemeSystem();
-    const fallbackLightTheme = React.useMemo(() => getDefaultTheme(false), []);
-    const fallbackDarkTheme = React.useMemo(() => getDefaultTheme(true), []);
-
-    const availableThemes = React.useMemo(
-        () => themeSystem?.availableThemes ?? [fallbackLightTheme, fallbackDarkTheme],
-        [fallbackDarkTheme, fallbackLightTheme, themeSystem?.availableThemes],
-    );
-    const lightThemeId = themeSystem?.lightThemeId ?? fallbackLightTheme.metadata.id;
-    const darkThemeId = themeSystem?.darkThemeId ?? fallbackDarkTheme.metadata.id;
-
-    const lightTheme = React.useMemo(
-        () => availableThemes.find((theme) => theme.metadata.id === lightThemeId) ?? fallbackLightTheme,
-        [availableThemes, fallbackLightTheme, lightThemeId],
-    );
-    const darkTheme = React.useMemo(
-        () => availableThemes.find((theme) => theme.metadata.id === darkThemeId) ?? fallbackDarkTheme,
-        [availableThemes, darkThemeId, fallbackDarkTheme],
-    );
-
-    React.useEffect(() => {
-        ensurePierreThemeRegistered(lightTheme);
-        ensurePierreThemeRegistered(darkTheme);
-    }, [darkTheme, lightTheme]);
-
-    const currentVariant = themeSystem?.currentTheme.metadata.variant ?? 'light';
-
-    return {
-        pierreTheme: { light: lightTheme.metadata.id, dark: darkTheme.metadata.id },
-        pierreThemeType: currentVariant === 'dark' ? ('dark' as const) : ('light' as const),
-    };
-};
-
 // Parse question tool output: "User has answered your questions: "Q1"="A1", "Q2"="A2". You can now..."
 const parseQuestionOutput = (output: string): Array<{ question: string; answer: string }> | null => {
     const match = output.match(/^User has answered your questions:\s*(.+?)\.\s*You can now/s);
@@ -1138,30 +1102,6 @@ const TaskToolSummary: React.FC<{
     );
 };
 
-interface DiffPreviewProps {
-    diff: string;
-    pierreTheme: { light: string; dark: string };
-    pierreThemeType: 'light' | 'dark';
-    diffViewMode: DiffViewMode;
-}
-
-const TOOL_DIFF_UNSAFE_CSS = `
-  [data-diff-header],
-  [data-diff] {
-    [data-separator] {
-      height: 24px !important;
-    }
-  }
-`;
-
-const TOOL_DIFF_METRICS = {
-    hunkLineCount: 50,
-    lineHeight: 24,
-    diffHeaderHeight: 44,
-    hunkSeparatorHeight: 24,
-    spacing: 0,
-};
-
 const TOOL_COLLAPSED_CUSTOM_STYLE: React.CSSProperties = {
     ...toolDisplayStyles.getCollapsedStyles(),
     padding: 0,
@@ -1260,85 +1200,18 @@ const renderAnimatedPathWithIcon = (path: string, animate = true, grow = true, s
     );
 };
 
-const PlainDiffFallback: React.FC<{ diff: string }> = ({ diff }) => (
-    <pre
-        className="m-0 overflow-auto whitespace-pre-wrap break-words rounded-lg p-2 typography-code"
-        style={{
-            backgroundColor: 'var(--syntax-base-background)',
-            color: 'var(--syntax-base-foreground)',
-        }}
-    >
-        {diff}
-    </pre>
+// The rich diff preview is the only tool-card piece that needs the
+// @pierre/diffs + Shiki stack; lazy-loading it keeps that stack out of the
+// eager chat graph. While the chunk loads, the plain-text patch renders as the
+// Suspense fallback, mirroring the preview's own error fallback.
+const LazyToolPartDiffPreview = lazyWithChunkRecovery(() => import('./ToolPartDiffPreview'));
+
+const DiffPreview: React.FC<{ diff: string; diffViewMode: DiffViewMode }> = ({ diff, diffViewMode }) => (
+    <React.Suspense fallback={<PlainDiffFallback diff={diff} />}>
+        <LazyToolPartDiffPreview diff={diff} diffViewMode={diffViewMode} />
+    </React.Suspense>
 );
 
-class DiffPreviewErrorBoundary extends React.Component<{
-    resetKey: string;
-    fallback: React.ReactNode;
-    children: React.ReactNode;
-}, { hasError: boolean }> {
-    state = { hasError: false };
-
-    static getDerivedStateFromError(): { hasError: boolean } {
-        return { hasError: true };
-    }
-
-    componentDidUpdate(prevProps: { resetKey: string }) {
-        if (prevProps.resetKey !== this.props.resetKey && this.state.hasError) {
-            this.setState({ hasError: false });
-        }
-    }
-
-    componentDidCatch(error: Error) {
-        if (process.env.NODE_ENV === 'development') {
-            console.warn('Tool diff preview failed; rendering raw patch instead.', error);
-        }
-    }
-
-    render() {
-        if (this.state.hasError) {
-            return this.props.fallback;
-        }
-        return this.props.children;
-    }
-}
-
-const DiffPreview: React.FC<DiffPreviewProps> = React.memo(({ diff, pierreTheme, pierreThemeType, diffViewMode }) => {
-    const options = React.useMemo(
-        () => ({
-            diffStyle: diffViewMode === 'side-by-side' ? 'split' as const : 'unified' as const,
-            diffIndicators: 'none' as const,
-            hunkSeparators: 'line-info-basic' as const,
-            lineDiffType: 'none' as const,
-            disableFileHeader: true,
-            maxLineDiffLength: 1000,
-            expansionLineCount: 20,
-            overflow: 'wrap' as const,
-            theme: pierreTheme,
-            themeType: pierreThemeType,
-            unsafeCSS: TOOL_DIFF_UNSAFE_CSS,
-        }),
-        [diffViewMode, pierreTheme, pierreThemeType]
-    );
-
-    const fallback = <PlainDiffFallback diff={diff} />;
-
-    return (
-        <div className="typography-code px-1 pb-1 pt-0">
-            <DiffPreviewErrorBoundary resetKey={diff} fallback={fallback}>
-                <PatchDiff
-                    patch={diff}
-                    metrics={TOOL_DIFF_METRICS}
-                    options={options}
-                    className="block w-full"
-                />
-            </DiffPreviewErrorBoundary>
-        </div>
-    );
-});
-
-DiffPreview.displayName = 'DiffPreview';
-
 interface ToolExpandedContentProps {
     part: ToolPartType;
     state: ToolStateUnion;
@@ -1357,7 +1230,6 @@ const ToolExpandedContent: React.FC<ToolExpandedContentProps> = React.memo(({
     const { t } = useI18n();
     const runtime = React.useContext(RuntimeAPIContext);
     const mobileActions = useMobileAppActions();
-    const { pierreTheme, pierreThemeType } = usePierreThemeConfig();
     const [diffViewMode, setDiffViewMode] = React.useState<DiffViewMode>('unified');
     const stateWithData = state as ToolStateWithMetadata;
     const metadata = stateWithData.metadata;
@@ -1633,8 +1505,6 @@ const ToolExpandedContent: React.FC<ToolExpandedContentProps> = React.memo(({
                             {entry.renderMode === 'diff' ? (
                                 <DiffPreview
                                     diff={entry.patch}
-                                    pierreTheme={pierreTheme}
-                                    pierreThemeType={pierreThemeType}
                                     diffViewMode={diffViewMode}
                                 />
                             ) : (
@@ -1753,8 +1623,6 @@ const ToolExpandedContent: React.FC<ToolExpandedContentProps> = React.memo(({
                                 ) : isWriteLikeTool && writeLikeInputPatch ? (
                                     <DiffPreview
                                         diff={writeLikeInputPatch}
-                                        pierreTheme={pierreTheme}
-                                        pierreThemeType={pierreThemeType}
                                         diffViewMode={diffViewMode}
                                     />
                                 ) : (
diff --git a/packages/ui/src/components/chat/message/parts/ToolPartDiffPreview.tsx b/packages/ui/src/components/chat/message/parts/ToolPartDiffPreview.tsx
new file mode 100644
index 00000000..7cfd6592
--- /dev/null
+++ b/packages/ui/src/components/chat/message/parts/ToolPartDiffPreview.tsx
@@ -0,0 +1,140 @@
+import React from 'react';
+import { PatchDiff } from '@pierre/diffs/react';
+
+import { useOptionalThemeSystem } from '@/contexts/useThemeSystem';
+import { ensurePierreThemeRegistered } from '@/lib/shiki/appThemeRegistry';
+import { getDefaultTheme } from '@/lib/theme/themes';
+import type { DiffViewMode } from '../DiffViewToggle';
+import { PlainDiffFallback } from './PlainDiffFallback';
+
+// Loaded lazily from ToolPart: this is the only part of the tool card that
+// needs @pierre/diffs' rendering stack (Shiki core + regex engines), so the
+// eager chat graph stays free of it and the chunk downloads on the first
+// rendered tool diff.
+
+const TOOL_DIFF_UNSAFE_CSS = `
+  [data-diff-header],
+  [data-diff] {
+    [data-separator] {
+      height: 24px !important;
+    }
+  }
+`;
+
+const TOOL_DIFF_METRICS = {
+    hunkLineCount: 50,
+    lineHeight: 24,
+    diffHeaderHeight: 44,
+    hunkSeparatorHeight: 24,
+    spacing: 0,
+};
+
+const usePierreThemeConfig = () => {
+    const themeSystem = useOptionalThemeSystem();
+    const fallbackLightTheme = React.useMemo(() => getDefaultTheme(false), []);
+    const fallbackDarkTheme = React.useMemo(() => getDefaultTheme(true), []);
+
+    const availableThemes = React.useMemo(
+        () => themeSystem?.availableThemes ?? [fallbackLightTheme, fallbackDarkTheme],
+        [fallbackDarkTheme, fallbackLightTheme, themeSystem?.availableThemes],
+    );
+    const lightThemeId = themeSystem?.lightThemeId ?? fallbackLightTheme.metadata.id;
+    const darkThemeId = themeSystem?.darkThemeId ?? fallbackDarkTheme.metadata.id;
+
+    const lightTheme = React.useMemo(
+        () => availableThemes.find((theme) => theme.metadata.id === lightThemeId) ?? fallbackLightTheme,
+        [availableThemes, fallbackLightTheme, lightThemeId],
+    );
+    const darkTheme = React.useMemo(
+        () => availableThemes.find((theme) => theme.metadata.id === darkThemeId) ?? fallbackDarkTheme,
+        [availableThemes, darkThemeId, fallbackDarkTheme],
+    );
+
+    // Registration is synchronous module state inside @pierre/diffs; rendering
+    // a PatchDiff with these theme ids requires it to have happened first, so
+    // register during render rather than in an effect.
+    ensurePierreThemeRegistered(lightTheme);
+    ensurePierreThemeRegistered(darkTheme);
+
+    const currentVariant = themeSystem?.currentTheme.metadata.variant ?? 'light';
+
+    return {
+        pierreTheme: { light: lightTheme.metadata.id, dark: darkTheme.metadata.id },
+        pierreThemeType: currentVariant === 'dark' ? ('dark' as const) : ('light' as const),
+    };
+};
+
+class DiffPreviewErrorBoundary extends React.Component<{
+    resetKey: string;
+    fallback: React.ReactNode;
+    children: React.ReactNode;
+}, { hasError: boolean }> {
+    state = { hasError: false };
+
+    static getDerivedStateFromError(): { hasError: boolean } {
+        return { hasError: true };
+    }
+
+    componentDidUpdate(prevProps: { resetKey: string }) {
+        if (prevProps.resetKey !== this.props.resetKey && this.state.hasError) {
+            this.setState({ hasError: false });
+        }
+    }
+
+    componentDidCatch(error: Error) {
+        if (process.env.NODE_ENV === 'development') {
+            console.warn('Tool diff preview failed; rendering raw patch instead.', error);
+        }
+    }
+
+    render() {
+        if (this.state.hasError) {
+            return this.props.fallback;
+        }
+        return this.props.children;
+    }
+}
+
+export interface ToolPartDiffPreviewProps {
+    diff: string;
+    diffViewMode: DiffViewMode;
+}
+
+const ToolPartDiffPreview: React.FC<ToolPartDiffPreviewProps> = React.memo(({ diff, diffViewMode }) => {
+    const { pierreTheme, pierreThemeType } = usePierreThemeConfig();
+    const options = React.useMemo(
+        () => ({
+            diffStyle: diffViewMode === 'side-by-side' ? 'split' as const : 'unified' as const,
+            diffIndicators: 'none' as const,
+            hunkSeparators: 'line-info-basic' as const,
+            lineDiffType: 'none' as const,
+            disableFileHeader: true,
+            maxLineDiffLength: 1000,
+            expansionLineCount: 20,
+            overflow: 'wrap' as const,
+            theme: pierreTheme,
+            themeType: pierreThemeType,
+            unsafeCSS: TOOL_DIFF_UNSAFE_CSS,
+        }),
+        [diffViewMode, pierreTheme, pierreThemeType]
+    );
+
+    const fallback = <PlainDiffFallback diff={diff} />;
+
+    return (
+        <div className="typography-code px-1 pb-1 pt-0">
+            <DiffPreviewErrorBoundary resetKey={diff} fallback={fallback}>
+                <PatchDiff
+                    patch={diff}
+                    metrics={TOOL_DIFF_METRICS}
+                    options={options}
+                    className="block w-full"
+                />
+            </DiffPreviewErrorBoundary>
+        </div>
+    );
+});
+
+ToolPartDiffPreview.displayName = 'ToolPartDiffPreview';
+
+export default ToolPartDiffPreview;
diff --git a/packages/ui/src/components/chat/message/parts/VirtualizedCodeBlock.tsx b/packages/ui/src/components/chat/message/parts/VirtualizedCodeBlock.tsx
index 11e7763f..5ef116d7 100644
--- a/packages/ui/src/components/chat/message/parts/VirtualizedCodeBlock.tsx
+++ b/packages/ui/src/components/chat/message/parts/VirtualizedCodeBlock.tsx
@@ -13,7 +13,7 @@
 import React from 'react';
 import { useVirtualizer } from '@tanstack/react-virtual';
 import { useThemeSystem } from '@/contexts/useThemeSystem';
-import { getMarkdownSyntaxVars } from '@/components/chat/markdown/markdownTheme';
+import { getMarkdownSyntaxVars } from '@/components/chat/markdown/markdownSyntaxVars';
 import { useWorkerHighlightedLines } from '@/components/code/useWorkerHighlightedLines';
 
 // ── Threshold: files smaller than this render without virtualization ──
diff --git a/packages/ui/src/components/code/WorkerHighlightedCode.tsx b/packages/ui/src/components/code/WorkerHighlightedCode.tsx
index 441972d8..60c5e3dd 100644
--- a/packages/ui/src/components/code/WorkerHighlightedCode.tsx
+++ b/packages/ui/src/components/code/WorkerHighlightedCode.tsx
@@ -1,7 +1,7 @@
 import React from 'react';
 import { cn } from '@/lib/utils';
 import { useThemeSystem } from '@/contexts/useThemeSystem';
-import { getMarkdownSyntaxVars } from '@/components/chat/markdown/markdownTheme';
+import { getMarkdownSyntaxVars } from '@/components/chat/markdown/markdownSyntaxVars';
 import { highlightCodeInWorker } from '@/components/chat/markdown/markdown-worker';
 
 // Shared static code highlighter backed by the markdown Shiki Web Worker.
diff --git a/packages/ui/src/components/layout/ContextPanel.tsx b/packages/ui/src/components/layout/ContextPanel.tsx
index d0b1f9c1..a8d5b159 100644
--- a/packages/ui/src/components/layout/ContextPanel.tsx
+++ b/packages/ui/src/components/layout/ContextPanel.tsx
@@ -4,13 +4,18 @@ import { FileTypeIcon } from '@/components/icons/FileTypeIcon';
 import { DiffViewIcon } from '@/components/icons/DiffIcon';
 import { Button } from '@/components/ui/button';
 import { SortableTabsStrip } from '@/components/ui/sortable-tabs-strip';
-import { DiffView } from '@/components/views/DiffView';
-import { FilesView } from '@/components/views/FilesView';
-import { GitView } from '@/components/views/GitView';
 import { PullRequestView } from '@/components/views/PullRequestView';
 import { TerminalView } from '@/components/views/TerminalView';
-import { WalkthroughView } from '@/components/views/walkthrough/WalkthroughView';
-import { PlanView } from '@/components/views/PlanView';
+import { lazyWithChunkRecovery } from '@/lib/chunkLoadRecovery';
+
+// Heavy views stay on-demand (same as MainLayout): importing DiffView/FilesView
+// or the walkthrough statically pulls the CodeMirror and @pierre/diffs stacks
+// into the eager startup graph even when no such tab is open.
+const WalkthroughView = lazyWithChunkRecovery(() => import('@/components/views/walkthrough/WalkthroughView').then((m) => ({ default: m.WalkthroughView })));
+const DiffView = lazyWithChunkRecovery(() => import('@/components/views/DiffView').then((m) => ({ default: m.DiffView })));
+const FilesView = lazyWithChunkRecovery(() => import('@/components/views/FilesView').then((m) => ({ default: m.FilesView })));
+const GitView = lazyWithChunkRecovery(() => import('@/components/views/GitView').then((m) => ({ default: m.GitView })));
+const PlanView = lazyWithChunkRecovery(() => import('@/components/views/PlanView').then((m) => ({ default: m.PlanView })));
 import { ProjectContextPanel } from './RightSidebarTabs';
 import { SidebarFilesTree } from './SidebarFilesTree';
 import { useThemeSystem } from '@/contexts/useThemeSystem';
@@ -2699,13 +2704,13 @@ export const ContextPanel: React.FC = () => {
   const activeNonChatContent = activeTab?.mode === 'context'
         ? <ContextPanelContent />
         : activeTab?.mode === 'git'
-            ? <GitView isActive={isOpen} />
+            ? <React.Suspense fallback={null}><GitView isActive={isOpen} /></React.Suspense>
             : activeTab?.mode === 'pr'
                 ? <PullRequestView />
             : activeTab?.mode === 'notes'
                 ? <ProjectContextPanel />
         : activeTab?.mode === 'plan'
-            ? <PlanView targetPath={activeTab.targetPath} />
+            ? <React.Suspense fallback={null}><PlanView targetPath={activeTab.targetPath} /></React.Suspense>
             : activeTab?.mode === 'preview'
                 ? <PreviewPane rawUrl={activeTab.targetPath ?? ''} onNavigate={(url) => openContextPreview(effectiveDirectory, url)} />
                 : (
@@ -2917,7 +2922,7 @@ export const ContextPanel: React.FC = () => {
           <div className={cn('absolute inset-0 flex', isFileTabActive ? 'flex' : 'hidden')}>
             <div className="h-full min-w-0 flex-1">
               {hasOpenEditorFile ? (
-                <FilesView mode="editor-only" />
+                <React.Suspense fallback={null}><FilesView mode="editor-only" /></React.Suspense>
               ) : (
                 <div className="flex h-full flex-col items-center justify-center gap-3 p-6 text-center">
                   <Icon name="file-code" className="h-12 w-12 text-muted-foreground/50" />
@@ -2983,16 +2988,18 @@ export const ContextPanel: React.FC = () => {
               activeTab?.id !== tab.id && 'hidden'
             )}
           >
-            <DiffView
-              hideStackedFileSidebar
-              stackedDefaultCollapsedAll
-              pinSelectedFileHeaderToTopOnNavigate
-              showOpenInEditorAction
-              diffScope={tab.diffScope ?? (tab.stagedDiff ? 'staged' : 'working')}
-              onDiffScopeChange={handleDiffScopeChange}
-              targetFilePath={tab.targetPath}
-              flushContent
-            />
+            <React.Suspense fallback={null}>
+              <DiffView
+                hideStackedFileSidebar
+                stackedDefaultCollapsedAll
+                pinSelectedFileHeaderToTopOnNavigate
+                showOpenInEditorAction
+                diffScope={tab.diffScope ?? (tab.stagedDiff ? 'staged' : 'working')}
+                onDiffScopeChange={handleDiffScopeChange}
+                targetFilePath={tab.targetPath}
+                flushContent
+              />
+            </React.Suspense>
           </div>
         ))}
         {hasTerminalTab ? (
@@ -3002,7 +3009,9 @@ export const ContextPanel: React.FC = () => {
         ) : null}
         {hasWalkthroughTab ? (
           <div className={cn('absolute inset-0', activeTab?.mode === 'walkthrough' ? 'block' : 'hidden')}>
-            <WalkthroughView directory={effectiveDirectory} />
+            <React.Suspense fallback={null}>
+              <WalkthroughView directory={effectiveDirectory} />
+            </React.Suspense>
           </div>
         ) : null}
         {activeTab?.mode !== 'chat' && !isFileTabActive && activeTab?.mode !== 'browser' && activeTab?.mode !== 'diff' && activeTab?.mode !== 'terminal' && activeTab?.mode !== 'walkthrough' ? activeNonChatContent : null}
diff --git a/packages/ui/src/components/layout/MainLayout.tsx b/packages/ui/src/components/layout/MainLayout.tsx
index b089d4e9..8755aae4 100644
--- a/packages/ui/src/components/layout/MainLayout.tsx
+++ b/packages/ui/src/components/layout/MainLayout.tsx
@@ -29,14 +29,16 @@ import { cn } from '@/lib/utils';
 import { lazyWithChunkRecovery } from '@/lib/chunkLoadRecovery';
 
 import { ChatView } from '@/components/views/ChatView';
-import { DiffView } from '@/components/views/DiffView';
-import { FilesView } from '@/components/views/FilesView';
-import { GitView } from '@/components/views/GitView';
-import { PlanView } from '@/components/views/PlanView';
 
 // Keep TerminalView eager: the bottom dock reserves its height immediately, so
 // suspending here leaves a large blank panel on slower machines.
-// Other heavy views stay on-demand to reduce initial bundle parse time.
+// Other heavy views stay on-demand to reduce initial bundle parse time:
+// DiffView/FilesView pull the CodeMirror and @pierre/diffs stacks into the
+// startup graph when imported statically.
+const PlanView = lazyWithChunkRecovery(() => import('@/components/views/PlanView').then(m => ({ default: m.PlanView })));
+const GitView = lazyWithChunkRecovery(() => import('@/components/views/GitView').then(m => ({ default: m.GitView })));
+const DiffView = lazyWithChunkRecovery(() => import('@/components/views/DiffView').then(m => ({ default: m.DiffView })));
+const FilesView = lazyWithChunkRecovery(() => import('@/components/views/FilesView').then(m => ({ default: m.FilesView })));
 const DiagramView = lazyWithChunkRecovery(() => import('@/components/views/DiagramView').then(m => ({ default: m.DiagramView })));
 const SettingsView = lazyWithChunkRecovery(() => import('@/components/views/SettingsView').then(m => ({ default: m.SettingsView })));
 const SettingsWindow = lazyWithChunkRecovery(() => import('@/components/views/SettingsWindow').then(m => ({ default: m.SettingsWindow })));
@@ -48,6 +50,17 @@ export const MainLayout: React.FC = () => {
     const isSessionSwitcherOpen = useUIStore((state) => state.isSessionSwitcherOpen);
     const isSettingsDialogOpen = useUIStore((state) => state.isSettingsDialogOpen);
     const setSettingsDialogOpen = useUIStore((state) => state.setSettingsDialogOpen);
+    // Mount the windowed settings dialog only after its first open: rendering
+    // the lazy component (even closed) makes React fetch the SettingsView
+    // chunk graph (CodeMirror editor, vim mode, theme tooling) on startup.
+    // Once opened it stays mounted so the close animation and state behave as
+    // before.
+    const [settingsWindowMounted, setSettingsWindowMounted] = React.useState(false);
+    React.useEffect(() => {
+        if (isSettingsDialogOpen) {
+            setSettingsWindowMounted(true);
+        }
+    }, [isSettingsDialogOpen]);
     const isMultiRunLauncherOpen = useUIStore((state) => state.isMultiRunLauncherOpen);
     const setMultiRunLauncherOpen = useUIStore((state) => state.setMultiRunLauncherOpen);
     const multiRunLauncherPrefillPrompt = useUIStore((state) => state.multiRunLauncherPrefillPrompt);
@@ -464,12 +477,14 @@ export const MainLayout: React.FC = () => {
                     </div>
 
                     {/* Desktop settings: windowed dialog with blur */}
-                    <React.Suspense fallback={null}>
-                        <SettingsWindow
-                            open={isSettingsDialogOpen}
-                            onOpenChange={setSettingsDialogOpen}
-                        />
-                    </React.Suspense>
+                    {settingsWindowMounted ? (
+                        <React.Suspense fallback={null}>
+                            <SettingsWindow
+                                open={isSettingsDialogOpen}
+                                onOpenChange={setSettingsDialogOpen}
+                            />
+                        </React.Suspense>
+                    ) : null}
                 </>
             )}
 
diff --git a/packages/ui/src/components/terminal/TerminalViewport.tsx b/packages/ui/src/components/terminal/TerminalViewport.tsx
index cd86497f..82657445 100644
--- a/packages/ui/src/components/terminal/TerminalViewport.tsx
+++ b/packages/ui/src/components/terminal/TerminalViewport.tsx
@@ -1,5 +1,5 @@
 import React from 'react';
-import { FitAddon, Ghostty, Terminal as GhosttyTerminal } from 'ghostty-web';
+import type { FitAddon, Ghostty, Terminal as GhosttyTerminal } from 'ghostty-web';
 
 import { cn } from '@/lib/utils';
 import type { TerminalTheme } from '@/lib/terminalTheme';
@@ -15,8 +15,33 @@ import {
 } from '@/lib/terminalTouchSelection';
 import type { TerminalChunk } from '@/stores/useTerminalStore';
 
-let ghosttyPromise: Promise<Ghostty> | null = null;
-const loadGhostty = (): Promise<Ghostty> => ghosttyPromise ??= Ghostty.load();
+// ghostty-web (638 KB raw of JS + the WASM VT) loads on demand: TerminalView
+// stays eagerly importable for the bottom dock without pulling the emulator
+// into the startup graph before a terminal is actually mounted.
+type GhosttyModule = typeof import('ghostty-web');
+type GhosttyRuntime = { module: GhosttyModule; ghostty: Ghostty };
+let ghosttyRuntimePromise: Promise<GhosttyRuntime> | null = null;
+const loadGhostty = (): Promise<GhosttyRuntime> =>
+  ghosttyRuntimePromise ??= import('ghostty-web').then(async (module) => ({
+    module,
+    ghostty: await module.Ghostty.load(),
+  }));
+
+// The web entry defers its ~2 MB Nerd Font download until a terminal actually
+// mounts (see the `__openchamberEnsureNerdFonts` hook in index.html). Wait for
+// it with a short bound so a cached font is in place before the glyph atlas is
+// built, while a cold CDN fetch never blocks the terminal from opening; the
+// runtimes without the hook (VS Code, mobile) resolve immediately.
+const NERD_FONT_WAIT_MS = 2000;
+const ensureNerdFonts = (): Promise<void> => {
+  if (typeof window === 'undefined') return Promise.resolve();
+  const loader = (window as typeof window & { __openchamberEnsureNerdFonts?: () => Promise<void> }).__openchamberEnsureNerdFonts;
+  if (typeof loader !== 'function') return Promise.resolve();
+  return Promise.race([
+    Promise.resolve(loader()).catch(() => undefined),
+    new Promise<void>((resolve) => setTimeout(resolve, NERD_FONT_WAIT_MS)),
+  ]).then(() => undefined);
+};
 
 type TerminalSize = { cols: number; rows: number };
 
@@ -211,13 +236,13 @@ const TerminalViewport = React.forwardRef<TerminalController, Props>(({
     window.addEventListener('focus', handleWindowFocus);
     window.addEventListener('blur', handleWindowBlur);
 
-    loadGhostty().then((ghostty) => {
+    Promise.all([loadGhostty(), ensureNerdFonts()]).then(([{ module, ghostty }]) => {
       if (disposed) return;
-      terminal = new GhosttyTerminal({
+      terminal = new module.Terminal({
         ...getGhosttyTerminalOptions(fontFamily, fontSize, theme, ghostty, false),
         ...(provisionalSizeRef.current ?? {}),
       });
-      const fitAddon = new FitAddon();
+      const fitAddon = new module.FitAddon();
       terminal.loadAddon(fitAddon);
       terminal.open(container);
       terminalRef.current = terminal;
diff --git a/packages/ui/src/components/ui/CommandPalette.tsx b/packages/ui/src/components/ui/CommandPalette.tsx
index 85cf5093..d54861be 100644
--- a/packages/ui/src/components/ui/CommandPalette.tsx
+++ b/packages/ui/src/components/ui/CommandPalette.tsx
@@ -41,7 +41,7 @@ import { canUseElectronDesktopIPC, invokeDesktop, isDesktopShell, isVSCodeRuntim
 import { SETTINGS_PAGE_METADATA, type SettingsRuntimeContext } from '@/lib/settings/metadata';
 
 const EMPTY_PINNED_SESSION_IDS = new Set<string>();
-import { getSettingsNavIcon } from '@/components/views/SettingsView';
+import { getSettingsNavIcon } from '@/lib/settings/metadata';
 import { Icon } from "@/components/icon/Icon";
 import { McpIcon } from '@/components/icons/McpIcon';
 import { scoreByFuzzyQuery } from '@/lib/search/fuzzySearch';
diff --git a/packages/ui/src/components/views/SettingsView.tsx b/packages/ui/src/components/views/SettingsView.tsx
index 74505195..cf3c6237 100644
--- a/packages/ui/src/components/views/SettingsView.tsx
+++ b/packages/ui/src/components/views/SettingsView.tsx
@@ -46,11 +46,11 @@ import { isDesktopLocalOriginActive, isDesktopShell, isVSCodeRuntime, isWebRunti
 import { isWindowsArm64 as isWindowsArm64Platform } from '@/lib/platform';
 import { useI18n } from '@/lib/i18n';
 import { Icon } from "@/components/icon/Icon";
-import type { IconName } from "@/components/icon/icons";
 import { McpIcon } from '@/components/icons/McpIcon';
 import { reloadOpenCodeConfiguration } from '@/stores/useAgentsStore';
 import {
   SETTINGS_PAGE_METADATA,
+  getSettingsNavIcon,
   getSettingsPageMeta,
   resolveSettingsSlug,
   type SettingsPageSlug,
@@ -113,7 +113,6 @@ const pageOrder: SettingsPageSlug[] = [
 
 const NAV_GROUP_ORDER = ['general', 'projects', 'opencode', 'content'] as const;
 
-const SNIPPETS_SETTINGS_ICON = { icon: 'chat-thread' } as const;
 const ADD_PROVIDER_SETTINGS_ID = '__add_provider__';
 
 function buildRuntimeContext(isDesktop: boolean, isMobile: boolean): SettingsRuntimeContext {
@@ -171,65 +170,6 @@ function getCurrentHistoryState(): Record<string, unknown> {
   return window.history.state;
 }
 
-// eslint-disable-next-line react-refresh/only-export-components
-export function getSettingsNavIcon(slug: SettingsPageSlug): IconName | null {
-  switch (slug) {
-    case 'general':
-      return 'settings-3';
-    case 'projects':
-      return 'folders';
-    case 'remote-instances':
-      return 'computer';
-    case 'appearance':
-      return 'palette';
-    case 'chat':
-      return 'chat-ai-3';
-    case 'magic-prompts':
-      return 'ai-generate-2';
-    case 'snippets':
-      return SNIPPETS_SETTINGS_ICON.icon;
-    case 'notifications':
-      return 'notification-3';
-    case 'shortcuts':
-      return 'command';
-    case 'sessions':
-      return 'chat-history';
-
-    case 'providers':
-      return 'cloud';
-    case 'agents':
-      return 'ai-agent';
-    case 'behavior':
-      return 'brain';
-    case 'commands':
-      return 'slash-commands-2';
-    case 'mcp':
-      return null;
-    case 'plugins':
-      return 'plug-2';
-
-    case 'skills.installed':
-      return 'book-open';
-    case 'skills.catalog':
-      return 'book';
-
-    case 'git':
-      return 'git-branch';
-
-    case 'usage':
-      return 'bar-chart-2';
-    case 'voice':
-      return 'mic';
-    case 'tunnel':
-      return 'home-office';
-    case 'about':
-      return 'information';
-    case 'home':
-      return null;
-    default:
-      return 'robot-2';
-  }
-}
 
 export const SettingsView: React.FC<SettingsViewProps> = ({ onClose, forceMobile, isWindowed, visiblePageSlugs, initialMobileStage = 'nav' }) => {
   const { t } = useI18n();
diff --git a/packages/ui/src/contexts/DiffWorkerProvider.tsx b/packages/ui/src/contexts/DiffWorkerProvider.tsx
index 2dafedc9..b95ef433 100644
--- a/packages/ui/src/contexts/DiffWorkerProvider.tsx
+++ b/packages/ui/src/contexts/DiffWorkerProvider.tsx
@@ -1,12 +1,16 @@
-import React, { useMemo, useEffect } from 'react';
+import React, { useEffect, useSyncExternalStore } from 'react';
 import type { SupportedLanguages } from '@pierre/diffs';
-import { WorkerPoolManager } from '@pierre/diffs/worker';
+import type { WorkerPoolManager } from '@pierre/diffs/worker';
 
 import { useOptionalThemeSystem } from './useThemeSystem';
-import { workerFactory } from '@/lib/diff/workerFactory';
-import { ensurePierreThemeRegistered } from '@/lib/shiki/appThemeRegistry';
 import { getDefaultTheme } from '@/lib/theme/themes';
+import type { Theme } from '@/types/theme';
 // NOTE: keep provider lightweight; avoid main-thread diff parsing here.
+// This module must not statically import `@pierre/diffs` runtime code:
+// `@pierre/diffs/worker` pulls the Shiki highlighter (core + oniguruma engine
+// + grammar registry) into the eager startup graph and `initialize()` spawns
+// workers plus a main-thread shared highlighter before any diff is visible.
+// Everything heavy loads on demand and is only warmed after startup idle.
 
 // Preload common languages for faster initial diff rendering
 const PRELOAD_LANGS: SupportedLanguages[] = [
@@ -38,68 +42,90 @@ const WORKER_POOL_CONFIG: Record<WorkerPoolStyle, { poolSize: number; totalASTLR
   },
 };
 
-let unifiedWorkerPool: WorkerPoolManager | undefined;
-let splitWorkerPool: WorkerPoolManager | undefined;
+type PoolModules = {
+  WorkerPoolManager: typeof WorkerPoolManager;
+  workerFactory: () => Worker;
+  ensurePierreThemeRegistered: (theme: Theme) => void;
+};
 
-const createWorkerPool = (style: WorkerPoolStyle) => {
-  const config = WORKER_POOL_CONFIG[style];
-  const pool = new WorkerPoolManager(
-    {
-      workerFactory,
-      poolSize: config.poolSize,
-      totalASTLRUCacheSize: config.totalASTLRUCacheSize,
-    },
-    {
-      theme: {
-        light: 'pierre-light',
-        dark: 'pierre-dark',
+let poolModulesPromise: Promise<PoolModules> | null = null;
+
+const loadPoolModules = (): Promise<PoolModules> => {
+  poolModulesPromise ??= Promise.all([
+    import('@pierre/diffs/worker'),
+    import('@/lib/diff/workerFactory'),
+    import('@/lib/shiki/appThemeRegistry'),
+  ]).then(([workerModule, factoryModule, themeRegistryModule]) => ({
+    WorkerPoolManager: workerModule.WorkerPoolManager,
+    workerFactory: factoryModule.workerFactory,
+    ensurePierreThemeRegistered: themeRegistryModule.ensurePierreThemeRegistered,
+  }));
+  return poolModulesPromise;
+};
+
+const pools: Partial<Record<WorkerPoolStyle, WorkerPoolManager>> = {};
+const poolsRequested = new Set<WorkerPoolStyle>();
+const poolListeners = new Set<() => void>();
+
+let currentRenderTheme: { light: string; dark: string } = {
+  light: 'pierre-light',
+  dark: 'pierre-dark',
+};
+
+const notifyPoolListeners = () => {
+  for (const listener of poolListeners) listener();
+};
+
+const applyRenderOptions = (style: WorkerPoolStyle, pool: WorkerPoolManager) => {
+  void pool.setRenderOptions({
+    theme: currentRenderTheme,
+    lineDiffType: WORKER_POOL_CONFIG[style].lineDiffType,
+  });
+};
+
+const ensurePool = (style: WorkerPoolStyle): void => {
+  if (typeof window === 'undefined' || poolsRequested.has(style)) return;
+  poolsRequested.add(style);
+  void loadPoolModules().then((modules) => {
+    if (pools[style]) return;
+    const config = WORKER_POOL_CONFIG[style];
+    const pool = new modules.WorkerPoolManager(
+      {
+        workerFactory: modules.workerFactory,
+        poolSize: config.poolSize,
+        totalASTLRUCacheSize: config.totalASTLRUCacheSize,
       },
-      langs: PRELOAD_LANGS,
-      lineDiffType: config.lineDiffType,
-      preferredHighlighter: 'shiki-wasm',
-    }
-  );
-  void pool.initialize();
-  return pool;
+      {
+        theme: {
+          light: 'pierre-light',
+          dark: 'pierre-dark',
+        },
+        langs: PRELOAD_LANGS,
+        lineDiffType: config.lineDiffType,
+        preferredHighlighter: 'shiki-wasm',
+      }
+    );
+    void pool.initialize();
+    pools[style] = pool;
+    applyRenderOptions(style, pool);
+    notifyPoolListeners();
+  });
 };
 
-const getWorkerPool = (style: WorkerPoolStyle): WorkerPoolManager | undefined => {
-  if (typeof window === 'undefined') {
-    return undefined;
-  }
-
-  if (style === 'split') {
-    splitWorkerPool ??= createWorkerPool('split');
-    return splitWorkerPool;
-  }
-
-  unifiedWorkerPool ??= createWorkerPool('unified');
-  return unifiedWorkerPool;
+const subscribeToPools = (listener: () => void): (() => void) => {
+  poolListeners.add(listener);
+  return () => poolListeners.delete(listener);
 };
 
-const WorkerPoolWarmup: React.FC<{
-  children: React.ReactNode;
-  renderTheme: { light: string; dark: string };
-}> = ({ children, renderTheme }) => {
-  const unifiedPool = useWorkerPool('unified');
-  const splitPool = useWorkerPool('split');
-
-  useEffect(() => {
-    if (unifiedPool) {
-      void unifiedPool.setRenderOptions({
-        theme: renderTheme,
-        lineDiffType: WORKER_POOL_CONFIG.unified.lineDiffType,
-      });
-    }
-    if (splitPool) {
-      void splitPool.setRenderOptions({
-        theme: renderTheme,
-        lineDiffType: WORKER_POOL_CONFIG.split.lineDiffType,
-      });
-    }
-  }, [renderTheme, splitPool, unifiedPool]);
-
-  return <>{children}</>;
+const setRenderTheme = (renderTheme: { light: string; dark: string }) => {
+  if (currentRenderTheme.light === renderTheme.light && currentRenderTheme.dark === renderTheme.dark) {
+    return;
+  }
+  currentRenderTheme = renderTheme;
+  for (const style of Object.keys(pools) as WorkerPoolStyle[]) {
+    const pool = pools[style];
+    if (pool) applyRenderOptions(style, pool);
+  }
 };
 
 export const DiffWorkerProvider: React.FC<DiffWorkerProviderProps> = ({ children }) => {
@@ -118,25 +144,54 @@ export const DiffWorkerProvider: React.FC<DiffWorkerProviderProps> = ({ children
     themeSystem?.availableThemes.find((theme) => theme.metadata.id === darkThemeId) ??
     fallbackDark;
 
-  ensurePierreThemeRegistered(lightTheme);
-  ensurePierreThemeRegistered(darkTheme);
+  // Register the active app themes with @pierre/diffs and forward them to any
+  // live pools. Registration goes through the deferred module load so the
+  // theme registry (and its @pierre/diffs import) stays out of the eager
+  // startup graph; each diff surface also registers the themes it renders
+  // with, so ordering is preserved even before this resolves.
+  useEffect(() => {
+    let cancelled = false;
+    void loadPoolModules().then((modules) => {
+      if (cancelled) return;
+      modules.ensurePierreThemeRegistered(lightTheme);
+      modules.ensurePierreThemeRegistered(darkTheme);
+      setRenderTheme({ light: lightTheme.metadata.id, dark: darkTheme.metadata.id });
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [darkTheme, lightTheme]);
 
-  const renderTheme = useMemo(
-    () => ({
-      light: lightTheme.metadata.id,
-      dark: darkTheme.metadata.id,
-    }),
-    [darkTheme.metadata.id, lightTheme.metadata.id],
-  );
+  // Warm the worker pools once startup work has settled so the first diff a
+  // user opens does not pay worker spawn + highlighter init. Idle-deferred:
+  // warming competed with initial load (3 workers, shiki grammars, oniguruma
+  // wasm) when it ran during mount.
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+    const warm = () => {
+      ensurePool('unified');
+      ensurePool('split');
+    };
+    if (typeof window.requestIdleCallback === 'function') {
+      const handle = window.requestIdleCallback(warm, { timeout: 5000 });
+      return () => window.cancelIdleCallback(handle);
+    }
+    const timeout = window.setTimeout(warm, 2000);
+    return () => window.clearTimeout(timeout);
+  }, []);
 
-  return (
-    <WorkerPoolWarmup renderTheme={renderTheme}>
-      {children}
-    </WorkerPoolWarmup>
-  );
+  return <>{children}</>;
 };
 
 // eslint-disable-next-line react-refresh/only-export-components
 export const useWorkerPool = (style: WorkerPoolStyle = 'unified'): WorkerPoolManager | undefined => {
-  return useMemo(() => getWorkerPool(style), [style]);
+  const pool = useSyncExternalStore(
+    subscribeToPools,
+    () => pools[style],
+    () => undefined,
+  );
+  useEffect(() => {
+    ensurePool(style);
+  }, [style]);
+  return pool;
 };
diff --git a/packages/ui/src/lib/settings/metadata.ts b/packages/ui/src/lib/settings/metadata.ts
index 9630ec1d..f8d96d72 100644
--- a/packages/ui/src/lib/settings/metadata.ts
+++ b/packages/ui/src/lib/settings/metadata.ts
@@ -1,4 +1,5 @@
 import type { SidebarSection } from '@/constants/sidebar';
+import type { IconName } from '@/components/icon/icons';
 
 export type SettingsPageSlug =
   | 'home'
@@ -237,3 +238,65 @@ export function resolveSettingsSlug(value: string | null | undefined): SettingsP
 
   return 'home';
 }
+
+// Lives here (not in SettingsView) so light consumers such as the command
+// palette can render settings entries without statically importing the whole
+// settings surface into the eager startup graph.
+export function getSettingsNavIcon(slug: SettingsPageSlug): IconName | null {
+  switch (slug) {
+    case 'general':
+      return 'settings-3';
+    case 'projects':
+      return 'folders';
+    case 'remote-instances':
+      return 'computer';
+    case 'appearance':
+      return 'palette';
+    case 'chat':
+      return 'chat-ai-3';
+    case 'magic-prompts':
+      return 'ai-generate-2';
+    case 'snippets':
+      return 'chat-thread';
+    case 'notifications':
+      return 'notification-3';
+    case 'shortcuts':
+      return 'command';
+    case 'sessions':
+      return 'chat-history';
+
+    case 'providers':
+      return 'cloud';
+    case 'agents':
+      return 'ai-agent';
+    case 'behavior':
+      return 'brain';
+    case 'commands':
+      return 'slash-commands-2';
+    case 'mcp':
+      return null;
+    case 'plugins':
+      return 'plug-2';
+
+    case 'skills.installed':
+      return 'book-open';
+    case 'skills.catalog':
+      return 'book';
+
+    case 'git':
+      return 'git-branch';
+
+    case 'usage':
+      return 'bar-chart-2';
+    case 'voice':
+      return 'mic';
+    case 'tunnel':
+      return 'home-office';
+    case 'about':
+      return 'information';
+    case 'home':
+      return null;
+    default:
+      return 'robot-2';
+  }
+}
diff --git a/packages/web/index.html b/packages/web/index.html
index 2434decd..45496b05 100644
--- a/packages/web/index.html
+++ b/packages/web/index.html
@@ -15,12 +15,6 @@
     <link rel="apple-touch-icon" sizes="167x167" href="/apple-touch-icon-167x167.png" />
     <link rel="apple-touch-icon" sizes="152x152" href="/apple-touch-icon-152x152.png" />
 
-    <!-- Preload Nerd Fonts for terminal icon display -->
-    <link rel="preload" href="https://cdn.jsdelivr.net/gh/mshaugh/nerdfont-webfonts@v3.3.0/build/fonts/JetBrainsMonoNerdFont-Regular.woff2"
-          as="font" type="font/woff2" crossorigin="anonymous">
-    <link rel="preload" href="https://cdn.jsdelivr.net/gh/mshaugh/nerdfont-webfonts@v3.3.0/build/fonts/FiraCodeNerdFont-Regular.woff2"
-          as="font" type="font/woff2" crossorigin="anonymous">
-
     <!-- Web app manifest (endpoint-first with data URL fallback) -->
     <script>
       const baseUrl = location.origin;
@@ -599,31 +593,41 @@
       }, 10000);
     </script>
 
-    <!-- CSS Font Loading API for reliable Nerd Font loading -->
+    <!-- CSS Font Loading API for reliable Nerd Font loading. The ~2 MB of
+         Nerd Fonts are only used by the terminal viewport, so they are no
+         longer downloaded on every cold start: the terminal requests them on
+         first mount through this idempotent hook. -->
     <script>
       (function() {
-        const fonts = [
-          {
-            name: 'JetBrainsMono Nerd Font',
-            url: 'https://cdn.jsdelivr.net/gh/mshaugh/nerdfont-webfonts@v3.3.0/build/fonts/JetBrainsMonoNerdFont-Regular.woff2'
-          },
-          {
-            name: 'FiraCode Nerd Font',
-            url: 'https://cdn.jsdelivr.net/gh/mshaugh/nerdfont-webfonts@v3.3.0/build/fonts/FiraCodeNerdFont-Regular.woff2'
+        let nerdFontsPromise = null;
+        window.__openchamberEnsureNerdFonts = function() {
+          if (nerdFontsPromise) {
+            return nerdFontsPromise;
           }
-        ];
+          const fonts = [
+            {
+              name: 'JetBrainsMono Nerd Font',
+              url: 'https://cdn.jsdelivr.net/gh/mshaugh/nerdfont-webfonts@v3.3.0/build/fonts/JetBrainsMonoNerdFont-Regular.woff2'
+            },
+            {
+              name: 'FiraCode Nerd Font',
+              url: 'https://cdn.jsdelivr.net/gh/mshaugh/nerdfont-webfonts@v3.3.0/build/fonts/FiraCodeNerdFont-Regular.woff2'
+            }
+          ];
 
-        const fontPromises = fonts.map(font => {
-          const fontFace = new FontFace(font.name, `url(${font.url}) format('woff2')`);
-          document.fonts.add(fontFace);
-          return fontFace.load().catch(err => {
-            console.warn(`Failed to load font: ${font.name}`, err);
+          const fontPromises = fonts.map(font => {
+            const fontFace = new FontFace(font.name, `url(${font.url}) format('woff2')`);
+            document.fonts.add(fontFace);
+            return fontFace.load().catch(err => {
+              console.warn(`Failed to load font: ${font.name}`, err);
+            });
           });
-        });
 
-        Promise.allSettled(fontPromises).then(() => {
-          document.documentElement.classList.add('fonts-loaded');
-        });
+          nerdFontsPromise = Promise.allSettled(fontPromises).then(() => {
+            document.documentElement.classList.add('fonts-loaded');
+          });
+          return nerdFontsPromise;
+        };
       })();
     </script>
 
diff --git a/packages/web/vite.config.ts b/packages/web/vite.config.ts
index 272f775a..60877c12 100644
--- a/packages/web/vite.config.ts
+++ b/packages/web/vite.config.ts
@@ -157,6 +157,28 @@ export default defineConfig({
           const segments = match.split('/');
           const packageName = match.startsWith('@') ? `${segments[0]}/${segments[1]}` : segments[0];
 
+          // Shiki grammars/themes and CodeMirror legacy modes are dynamically
+          // imported one at a time by their registries. Forcing them into a
+          // single vendor chunk makes the first language request download every
+          // grammar (7.4 MB raw for @shikijs/langs). Let Rollup split them per
+          // dynamically imported module so only used languages are fetched —
+          // the worker build already behaves this way.
+          if (
+            packageName === '@shikijs/langs' ||
+            packageName === '@shikijs/themes' ||
+            packageName === '@codemirror/legacy-modes'
+          ) {
+            return undefined;
+          }
+
+          // Split @pierre/diffs by usage as well: the eager tool renderer needs
+          // only its pure patch parser, while the Shiki-importing render stack
+          // must stay loadable on demand. One merged vendor chunk would make
+          // the parser import download the whole stack eagerly.
+          if (packageName === '@pierre/diffs') {
+            return undefined;
+          }
+
           if (packageName === 'react' || packageName === 'react-dom') return 'vendor-react';
           if (packageName === 'zustand' || packageName === 'zustand/middleware') return 'vendor-zustand';
 
diff --git a/vite.config.ts b/vite.config.ts
index ae9721f4..bcaf5d27 100644
--- a/vite.config.ts
+++ b/vite.config.ts
@@ -55,6 +55,28 @@ export default defineConfig({
           const segments = match.split('/')
           const packageName = match.startsWith('@') ? `${segments[0]}/${segments[1]}` : segments[0]
 
+          // Shiki grammars/themes and CodeMirror legacy modes are dynamically
+          // imported one at a time by their registries. Forcing them into a
+          // single vendor chunk makes the first language request download every
+          // grammar (7.4 MB raw for @shikijs/langs). Let Rollup split them per
+          // dynamically imported module so only used languages are fetched —
+          // the worker build already behaves this way.
+          if (
+            packageName === '@shikijs/langs' ||
+            packageName === '@shikijs/themes' ||
+            packageName === '@codemirror/legacy-modes'
+          ) {
+            return undefined
+          }
+
+          // Split @pierre/diffs by usage as well: the eager tool renderer needs
+          // only its pure patch parser, while the Shiki-importing render stack
+          // must stay loadable on demand. One merged vendor chunk would make
+          // the parser import download the whole stack eagerly.
+          if (packageName === '@pierre/diffs') {
+            return undefined
+          }
+
           if (packageName === 'react' || packageName === 'react-dom') return 'vendor-react'
           if (packageName === 'zustand' || packageName === 'zustand/middleware') return 'vendor-zustand'
           if (packageName === '@opencode-ai/sdk') return 'vendor-opencode-sdk'

From 3fc136c95e7fd3ac27d5b39653363bc7eaea3fa1 Mon Sep 17 00:00:00 2001
From: Serhii Dziupin <serkraser@gmail.com>
Date: Fri, 7 Aug 2026 09:09:32 +0300
Subject: [PATCH 55/57] fix(terminal): keep default terminal tab names unique
 after closing tabs (#2718) (#2731)

---
 .../ui/src/stores/useTerminalStore.test.ts    | 35 +++++++++++++++++++
 packages/ui/src/stores/useTerminalStore.ts    | 24 +++++++++++--
 2 files changed, 57 insertions(+), 2 deletions(-)

diff --git a/packages/ui/src/stores/useTerminalStore.test.ts b/packages/ui/src/stores/useTerminalStore.test.ts
index 773f1152..c60f0ffd 100644
--- a/packages/ui/src/stores/useTerminalStore.test.ts
+++ b/packages/ui/src/stores/useTerminalStore.test.ts
@@ -123,3 +123,38 @@ describe('terminal state reconciliation', () => {
     expect(useTerminalStore.getState().buffers.size).toBe(0);
   });
 });
+
+describe('default terminal tab labels', () => {
+  afterEach(() => useTerminalStore.getState().clearAll());
+
+  const labels = () =>
+    useTerminalStore.getState().getDirectoryState('/repo')!.tabs.map((tab) => tab.label);
+
+  // Regression for https://github.com/openchamber/openchamber/issues/2718
+  test('does not reuse the number of a closed tab', () => {
+    const first = setup();
+    useTerminalStore.getState().createTab('/repo');
+    expect(labels()).toEqual(['Terminal', 'Terminal 2']);
+
+    useTerminalStore.getState().closeTab('/repo', first);
+    useTerminalStore.getState().createTab('/repo');
+
+    expect(labels()).toEqual(['Terminal 2', 'Terminal 3']);
+  });
+
+  test('numbers past a user-renamed "Terminal N" label instead of duplicating it', () => {
+    const first = setup();
+    useTerminalStore.getState().setTabLabel('/repo', first, 'Terminal 5');
+    useTerminalStore.getState().createTab('/repo');
+
+    expect(labels()).toEqual(['Terminal 5', 'Terminal 6']);
+  });
+
+  test('ignores custom labels and starts over at "Terminal" when no default-labeled tabs remain', () => {
+    const first = setup();
+    useTerminalStore.getState().setTabLabel('/repo', first, 'build');
+    useTerminalStore.getState().createTab('/repo');
+
+    expect(labels()).toEqual(['build', 'Terminal']);
+  });
+});
diff --git a/packages/ui/src/stores/useTerminalStore.ts b/packages/ui/src/stores/useTerminalStore.ts
index 6b68d32a..485717ff 100644
--- a/packages/ui/src/stores/useTerminalStore.ts
+++ b/packages/ui/src/stores/useTerminalStore.ts
@@ -157,6 +157,27 @@ function normalizeDirectory(dir: string): string {
   return normalized;
 }
 
+const DEFAULT_TAB_LABEL_PATTERN = /^Terminal(?: (\d+))?$/;
+
+/**
+ * Default labels must stay unique among the directory's open tabs even after
+ * closes (#2718), so number from the highest existing "Terminal N" suffix
+ * instead of the live tab count. Labels are persisted with the tabs, so the
+ * derivation also survives reloads without a dedicated counter. User-renamed
+ * labels only participate when they match the default pattern; they are never
+ * rewritten.
+ */
+const nextDefaultTabLabel = (tabs: readonly TerminalTab[]): string => {
+  let highest = 0;
+  for (const tab of tabs) {
+    const match = DEFAULT_TAB_LABEL_PATTERN.exec(tab.label);
+    if (!match) continue;
+    const value = match[1] ? Number.parseInt(match[1], 10) : 1;
+    if (Number.isSafeInteger(value)) highest = Math.max(highest, value);
+  }
+  return highest === 0 ? 'Terminal' : `Terminal ${highest + 1}`;
+};
+
 const createEmptyTab = (id: string, label: string): TerminalTab => ({
   id,
   terminalSessionId: null,
@@ -295,8 +316,7 @@ export const useTerminalStore = create<TerminalStore>()(
             const existing = newSessions.get(key);
 
             const nextTabId = state.nextTabId + 1;
-            const labelIndex = (existing?.tabs.length ?? 0) + 1;
-            const label = `Terminal ${labelIndex}`;
+            const label = nextDefaultTabLabel(existing?.tabs ?? []);
             const tab = createEmptyTab(tabId, label);
 
             if (!existing) {

From 87dbc59bf18016d094c5ad9861c67044831444b3 Mon Sep 17 00:00:00 2001
From: Serhii Dziupin <serkraser@gmail.com>
Date: Fri, 7 Aug 2026 09:16:34 +0300
Subject: [PATCH 56/57] fix(chat): do not replay entry animations for
 already-seen fresh messages (#2124) (#2732)

---
 packages/ui/src/lib/messageFreshness.test.ts | 85 ++++++++++++++++++++
 packages/ui/src/lib/messageFreshness.ts      | 11 ++-
 2 files changed, 92 insertions(+), 4 deletions(-)
 create mode 100644 packages/ui/src/lib/messageFreshness.test.ts

diff --git a/packages/ui/src/lib/messageFreshness.test.ts b/packages/ui/src/lib/messageFreshness.test.ts
new file mode 100644
index 00000000..bd59bffd
--- /dev/null
+++ b/packages/ui/src/lib/messageFreshness.test.ts
@@ -0,0 +1,85 @@
+import { beforeEach, describe, expect, test } from 'bun:test';
+
+import { MessageFreshnessDetector } from './messageFreshness';
+
+import type { Message } from '@opencode-ai/sdk/v2';
+
+const makeAssistantMessage = (id: string, created: number): Message =>
+    ({
+        id,
+        role: 'assistant',
+        sessionID: 'session-a',
+        time: { created },
+    }) as unknown as Message;
+
+describe('MessageFreshnessDetector.shouldAnimateMessage', () => {
+    let detector: MessageFreshnessDetector;
+
+    beforeEach(() => {
+        detector = MessageFreshnessDetector.getInstance();
+        detector.clearAll();
+    });
+
+    test('fresh message animates once and is recorded as seen', () => {
+        detector.recordSessionStart('session-a');
+        const message = makeAssistantMessage('msg-fresh', Date.now());
+
+        expect(detector.shouldAnimateMessage(message, 'session-a')).toBe(true);
+        expect(detector.hasBeenAnimated('msg-fresh')).toBe(true);
+    });
+
+    test('regression #2124: fresh message does not re-animate when returning to the session', () => {
+        detector.recordSessionStart('session-a');
+        const message = makeAssistantMessage('msg-fresh', Date.now());
+
+        // First visit: the message is fresh and animates.
+        expect(detector.shouldAnimateMessage(message, 'session-a')).toBe(true);
+
+        // User switches away and back; ChatViewport remounts and re-evaluates
+        // before recordSessionStart runs again, so the old session start time
+        // is still in effect. The message must not animate a second time.
+        expect(detector.shouldAnimateMessage(message, 'session-a')).toBe(false);
+    });
+
+    test('stale history message never animates and is recorded as seen', () => {
+        detector.recordSessionStart('session-a');
+        const message = makeAssistantMessage('msg-old', Date.now() - 60_000);
+
+        expect(detector.shouldAnimateMessage(message, 'session-a')).toBe(false);
+        expect(detector.hasBeenAnimated('msg-old')).toBe(true);
+        expect(detector.shouldAnimateMessage(message, 'session-a')).toBe(false);
+    });
+
+    test('message evaluated without a recorded session start does not animate and is recorded', () => {
+        const message = makeAssistantMessage('msg-no-session', Date.now());
+
+        expect(detector.shouldAnimateMessage(message, 'session-a')).toBe(false);
+        expect(detector.hasBeenAnimated('msg-no-session')).toBe(true);
+
+        // Recording the session start afterwards must not resurrect the animation.
+        detector.recordSessionStart('session-a');
+        expect(detector.shouldAnimateMessage(message, 'session-a')).toBe(false);
+    });
+
+    test('non-assistant messages never animate', () => {
+        detector.recordSessionStart('session-a');
+        const message = {
+            id: 'msg-user',
+            role: 'user',
+            sessionID: 'session-a',
+            time: { created: Date.now() },
+        } as unknown as Message;
+
+        expect(detector.shouldAnimateMessage(message, 'session-a')).toBe(false);
+    });
+
+    test('a new fresh message still animates after older fresh messages were seen', () => {
+        detector.recordSessionStart('session-a');
+        const first = makeAssistantMessage('msg-first', Date.now());
+        const second = makeAssistantMessage('msg-second', Date.now());
+
+        expect(detector.shouldAnimateMessage(first, 'session-a')).toBe(true);
+        expect(detector.shouldAnimateMessage(second, 'session-a')).toBe(true);
+        expect(detector.shouldAnimateMessage(second, 'session-a')).toBe(false);
+    });
+});
diff --git a/packages/ui/src/lib/messageFreshness.ts b/packages/ui/src/lib/messageFreshness.ts
index e32c5843..230a747c 100644
--- a/packages/ui/src/lib/messageFreshness.ts
+++ b/packages/ui/src/lib/messageFreshness.ts
@@ -44,10 +44,13 @@ export class MessageFreshnessDetector {
 
         const isFresh = message.time.created > (sessionStartTime - 5000);
 
-        if (!isFresh) {
-            this.seenMessageIds.add(message.id);
-            this.messageCreationTimes.set(message.id, message.time.created);
-        }
+        // Record fresh messages too so they animate at most once per detector
+        // lifetime. The detector is a module singleton that outlives ChatViewport
+        // remounts; without this, switching away and back re-evaluates the same
+        // message against the stale session start time (recordSessionStart runs
+        // in an effect after the first render) and replays the entry animation.
+        this.seenMessageIds.add(message.id);
+        this.messageCreationTimes.set(message.id, message.time.created);
 
         return isFresh;
     }

From 10606d79d31b2f19cecd62495cd1d94077b60644 Mon Sep 17 00:00:00 2001
From: Serhii Dziupin <serkraser@gmail.com>
Date: Fri, 7 Aug 2026 09:52:48 +0300
Subject: [PATCH 57/57] fix(git): enable core.longpaths for worktree population
 (#2746) (#2747)

* fix(git): enable core.longpaths for worktree population

Worktrees live under a deep OpenCode data-dir path, so Windows checkouts
of deeply nested repos failed bootstrap with "Filename too long". Enable
Git core.longpaths before git reset --hard (web + VS Code) and surface
clearer path-length guidance when the filesystem still rejects a path.

Fixes #2746

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>

* chore(vscode): keep ensureWorktreeLongpaths private

Avoid an unused export in the VS Code git service; the helper stays
local to populateWorktreeWithLockRecovery.

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>
---
 packages/vscode/src/DOCUMENTATION.md          |   1 +
 packages/vscode/src/gitService.ts             |  54 ++++-
 packages/web/server/lib/git/DOCUMENTATION.md  |   1 +
 .../lib/git/issue-2746-longpaths.test.js      | 206 ++++++++++++++++++
 packages/web/server/lib/git/service.js        |  53 ++++-
 5 files changed, 301 insertions(+), 14 deletions(-)
 create mode 100644 packages/web/server/lib/git/issue-2746-longpaths.test.js

diff --git a/packages/vscode/src/DOCUMENTATION.md b/packages/vscode/src/DOCUMENTATION.md
index 9218e072..d611986c 100644
--- a/packages/vscode/src/DOCUMENTATION.md
+++ b/packages/vscode/src/DOCUMENTATION.md
@@ -25,6 +25,7 @@ Keep `bridge.ts` as a thin orchestration layer that delegates message handling t
   - Owns VS Code Git and worktree operations.
   - Fast worktree creation reports bootstrap phases explicitly: `directory-created`, then `git-ready` after Git population/upstream work, and `setup-ready` after setup commands. Existing worktrees without tracked bootstrap state fall back to `ready`/`setup-ready`; shared webview consumers also accept legacy responses without `phase`.
   - Worktree removal waits for an active create/bootstrap task for the same directory so background Git and setup work cannot race deletion or restore stale bootstrap state.
+  - Worktree population enables Git `core.longpaths` (local repo config plus `-c core.longpaths=true` on `git reset --hard`) so deeply nested checkouts under the managed data-dir worktree root do not fail on Windows MAX_PATH with "Filename too long".
 
 - `bridge-fs-runtime.ts`
   - Bridge handlers for filesystem-related message routes.
diff --git a/packages/vscode/src/gitService.ts b/packages/vscode/src/gitService.ts
index 7f2a67d6..97b3a4d1 100644
--- a/packages/vscode/src/gitService.ts
+++ b/packages/vscode/src/gitService.ts
@@ -1117,34 +1117,71 @@ const getFileIdentity = async (filePath: string): Promise<string | null> => {
   }
 };
 
+// OpenChamber places managed worktrees under a deep data-dir path
+// (`<XDG_DATA_HOME>/opencode/worktree/<40-char project id>/<name>/`). On
+// Windows that prefix plus a deeply nested repo file routinely exceeds
+// MAX_PATH (260). Git can check those paths out when core.longpaths is
+// enabled; without it, `git reset --hard` during bootstrap fails with
+// "Filename too long" and leaves a half-populated worktree (issue #2746).
+const WORKTREE_POPULATE_RESET_ARGS = ['-c', 'core.longpaths=true', 'reset', '--hard'] as const;
+
+const isFilenameTooLongError = (message: string | null | undefined): boolean =>
+  /file ?name too long/i.test(String(message || ''));
+
+const formatWorktreePopulateError = (message: string | null | undefined): string => {
+  const text = String(message || '').trim() || 'Failed to populate worktree';
+  if (!isFilenameTooLongError(text)) {
+    return text;
+  }
+  return [
+    text,
+    'The worktree checkout path exceeds this system\'s path-length limit.',
+    'OpenChamber enables Git `core.longpaths` for worktree population; if this still fails on Windows, enable OS long paths (LongPathsEnabled) or open the repository from a shorter absolute path.',
+  ].join('\n');
+};
+
+const ensureWorktreeLongpaths = async (directory: string): Promise<void> => {
+  const current = await runGitCommand(directory, ['config', '--get', 'core.longpaths']);
+  if (String(current.stdout || '').trim().toLowerCase() === 'true') {
+    return;
+  }
+  // Local config is shared across linked worktrees via the common git dir, so
+  // subsequent OpenChamber and CLI git operations in this repo also get long
+  // path support. Failures here are non-fatal: populate still passes
+  // `-c core.longpaths=true` on reset.
+  await runGitCommand(directory, ['config', 'core.longpaths', 'true']);
+};
+
 const populateWorktreeWithLockRecovery = async (directory: string): Promise<void> => {
-  let result = await runGitCommand(directory, ['reset', '--hard']);
+  await ensureWorktreeLongpaths(directory);
+
+  let result = await runGitCommand(directory, [...WORKTREE_POPULATE_RESET_ARGS]);
   if (result.success) {
     return;
   }
   if (!isIndexLockError(result)) {
-    throw new Error(result.message || 'Failed to populate worktree');
+    throw new Error(formatWorktreePopulateError(result.message));
   }
 
   await wait(WORKTREE_INDEX_LOCK_RETRY_DELAY_MS);
-  result = await runGitCommand(directory, ['reset', '--hard']);
+  result = await runGitCommand(directory, [...WORKTREE_POPULATE_RESET_ARGS]);
   if (result.success) {
     return;
   }
   if (!isIndexLockError(result)) {
-    throw new Error(result.message || 'Failed to populate worktree');
+    throw new Error(formatWorktreePopulateError(result.message));
   }
 
   const lockPath = await getWorktreeIndexLockPath(directory);
   const identity = lockPath ? await getFileIdentity(lockPath) : null;
   await wait(WORKTREE_INDEX_LOCK_STALE_DELAY_MS);
 
-  result = await runGitCommand(directory, ['reset', '--hard']);
+  result = await runGitCommand(directory, [...WORKTREE_POPULATE_RESET_ARGS]);
   if (result.success) {
     return;
   }
   if (!isIndexLockError(result) || !lockPath || !identity || await getFileIdentity(lockPath) !== identity) {
-    throw new Error(result.message || 'Failed to populate worktree');
+    throw new Error(formatWorktreePopulateError(result.message));
   }
 
   await fs.promises.unlink(lockPath).catch((error) => {
@@ -1152,7 +1189,10 @@ const populateWorktreeWithLockRecovery = async (directory: string): Promise<void
       throw error;
     }
   });
-  await runGitCommandOrThrow(directory, ['reset', '--hard'], 'Failed to populate worktree');
+  const finalResult = await runGitCommand(directory, [...WORKTREE_POPULATE_RESET_ARGS]);
+  if (!finalResult.success) {
+    throw new Error(formatWorktreePopulateError(finalResult.message || 'Failed to populate worktree'));
+  }
 };
 
 // Worktrees are created with `git worktree add --no-checkout` and populated
diff --git a/packages/web/server/lib/git/DOCUMENTATION.md b/packages/web/server/lib/git/DOCUMENTATION.md
index ec45bc5d..10743664 100644
--- a/packages/web/server/lib/git/DOCUMENTATION.md
+++ b/packages/web/server/lib/git/DOCUMENTATION.md
@@ -136,6 +136,7 @@ The following functions are internal helpers used by exported functions:
 - Fast-create background failures remove OpenCode sandbox metadata for directories that never became Git worktrees, and remove the pre-created directory only if it is still empty. User-created files are never recursively deleted by this cleanup.
 - Worktree removal waits for any active create/bootstrap task for that directory before deleting it, preventing a background Git or setup task from restoring removed state or racing filesystem cleanup.
 - Worktree bootstrap retries transient `index.lock` conflicts. If the lock remains byte-for-byte and metadata-identical across the retry window, it is treated as stale, removed, and population continues automatically; changing locks are left untouched and reported as failures.
+- Worktree population enables Git `core.longpaths` (local repo config plus `-c core.longpaths=true` on `git reset --hard`) so deeply nested checkouts under the managed data-dir worktree root do not fail on Windows MAX_PATH with "Filename too long". Path-component limits that the filesystem itself rejects still fail bootstrap, with a clearer path-length guidance message.
 
 ### Log Response
 - `all`: Array of commit objects with hash, date, message, author info, stats.
diff --git a/packages/web/server/lib/git/issue-2746-longpaths.test.js b/packages/web/server/lib/git/issue-2746-longpaths.test.js
new file mode 100644
index 00000000..3864df4d
--- /dev/null
+++ b/packages/web/server/lib/git/issue-2746-longpaths.test.js
@@ -0,0 +1,206 @@
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import {
+  createWorktree,
+  ensureWorktreeLongpaths,
+  getWorktreeBootstrapStatus,
+  populateWorktreeWithLockRecovery,
+} from './service.js';
+
+// ---------------------------------------------------------------------------
+// Regression for https://github.com/openchamber/openchamber/issues/2746
+//
+// "[Bug] new worktree， Filename too long"
+//
+// OpenChamber places worktrees under:
+//   <XDG_DATA_HOME>/opencode/worktree/<40-char root commit hash>/<worktree name>
+// and populates them with `git reset --hard`. On Windows, that deep prefix plus
+// a deeply nested repo file (e.g. yudao ~173 chars) exceeds MAX_PATH (260) and
+// git aborts with "Filename too long" unless `core.longpaths` is enabled.
+// ---------------------------------------------------------------------------
+
+const tempDirs = [];
+
+const createTempDir = () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'openchamber-git-issue2746-'));
+  tempDirs.push(dir);
+  return dir;
+};
+
+const runGit = (cwd, args, input) =>
+  execFileSync('git', args, {
+    cwd,
+    encoding: 'utf8',
+    input,
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+
+const canRunGit = () => {
+  try {
+    execFileSync('git', ['--version'], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+describe('issue #2746 - worktree long path support', () => {
+  it('enables core.longpaths and populates a deeply nested worktree checkout', async () => {
+    if (!canRunGit()) return;
+
+    const previousXdgDataHome = process.env.XDG_DATA_HOME;
+    const dataHome = createTempDir();
+    process.env.XDG_DATA_HOME = dataHome;
+
+    try {
+      const repo = createTempDir();
+      runGit(repo, ['init', '-b', 'main']);
+      runGit(repo, ['config', 'user.email', 'test@example.com']);
+      runGit(repo, ['config', 'user.name', 'Test User']);
+
+      // Realistic reporter path: many nested segments, each component well under
+      // NAME_MAX. On Windows the managed worktree prefix + this relative path
+      // exceeds MAX_PATH unless core.longpaths is enabled.
+      const deepRelative = path.join(
+        'server',
+        'yudao-framework',
+        'yudao-spring-boot-starter-biz-data-permission',
+        'src',
+        'main',
+        'java',
+        'cn',
+        'iocoder',
+        'yudao',
+        'framework',
+        'datapermission',
+        'config',
+        'YudaoDataPermissionAutoConfiguration.java',
+      );
+      fs.mkdirSync(path.dirname(path.join(repo, deepRelative)), { recursive: true });
+      fs.writeFileSync(path.join(repo, deepRelative), '// yudao\n');
+      fs.writeFileSync(path.join(repo, 'README.md'), '# Test\n');
+      runGit(repo, ['add', 'README.md', deepRelative]);
+      runGit(repo, ['commit', '-qm', 'init']);
+
+      const created = await createWorktree(repo, {
+        mode: 'new',
+        worktreeName: 'issue-2746',
+        branchName: 'openchamber/issue-2746',
+      });
+      expect(created.directoryCreated).toBe(true);
+
+      await expect.poll(async () => {
+        const status = await getWorktreeBootstrapStatus(created.path);
+        return status?.status;
+      }, { timeout: 10_000 }).toBe('ready');
+
+      const longpaths = runGit(created.path, ['config', '--get', 'core.longpaths']).trim();
+      expect(longpaths).toBe('true');
+      expect(fs.existsSync(path.join(created.path, deepRelative))).toBe(true);
+      expect(fs.existsSync(path.join(created.path, 'README.md'))).toBe(true);
+    } finally {
+      if (previousXdgDataHome === undefined) {
+        delete process.env.XDG_DATA_HOME;
+      } else {
+        process.env.XDG_DATA_HOME = previousXdgDataHome;
+      }
+    }
+  });
+
+  it('ensureWorktreeLongpaths is idempotent when already enabled', async () => {
+    if (!canRunGit()) return;
+
+    const repo = createTempDir();
+    runGit(repo, ['init', '-b', 'main']);
+    runGit(repo, ['config', 'user.email', 'test@example.com']);
+    runGit(repo, ['config', 'user.name', 'Test User']);
+    fs.writeFileSync(path.join(repo, 'README.md'), '# Test\n');
+    runGit(repo, ['add', 'README.md']);
+    runGit(repo, ['commit', '-qm', 'init']);
+    runGit(repo, ['config', 'core.longpaths', 'true']);
+
+    await expect(ensureWorktreeLongpaths(repo)).resolves.toBeUndefined();
+    expect(runGit(repo, ['config', '--get', 'core.longpaths']).trim()).toBe('true');
+  });
+
+  it('surfaces guided bootstrap failure when a path component exceeds the filesystem name limit', async () => {
+    if (!canRunGit()) return;
+
+    const previousXdgDataHome = process.env.XDG_DATA_HOME;
+    const dataHome = createTempDir();
+    process.env.XDG_DATA_HOME = dataHome;
+
+    try {
+      const repo = createTempDir();
+      runGit(repo, ['init', '-b', 'main']);
+      runGit(repo, ['config', 'user.email', 'test@example.com']);
+      runGit(repo, ['config', 'user.name', 'Test User']);
+
+      // Linux/macOS NAME_MAX equivalent of the Windows failure mode: a single
+      // path component longer than 255 cannot be materialized. core.longpaths
+      // cannot fix this; bootstrap must fail clearly instead of leaving a
+      // silent half-populated worktree.
+      const longComponent = 'x'.repeat(300);
+      const longPath = `server/${longComponent}/YudaoDataPermissionAutoConfiguration.java`;
+      const blobHash = runGit(repo, ['hash-object', '-w', '--stdin'], '// test\n').trim();
+      runGit(repo, ['update-index', '--add', '--cacheinfo', `100644,${blobHash},${longPath}`]);
+      runGit(repo, ['commit', '-qm', 'init']);
+      fs.writeFileSync(path.join(repo, 'README.md'), '# Test\n');
+      runGit(repo, ['add', 'README.md']);
+      runGit(repo, ['commit', '-qm', 'add readme']);
+
+      const created = await createWorktree(repo, {
+        mode: 'new',
+        worktreeName: 'issue-2746-namemax',
+        branchName: 'openchamber/issue-2746-namemax',
+      });
+      expect(created.directoryCreated).toBe(true);
+
+      await expect.poll(async () => {
+        const status = await getWorktreeBootstrapStatus(created.path);
+        return status?.status;
+      }, { timeout: 10_000 }).toBe('failed');
+
+      const status = await getWorktreeBootstrapStatus(created.path);
+      expect(status?.error).toMatch(/file name too long|filename too long/i);
+      expect(status?.error).toMatch(/path-length limit/i);
+      expect(runGit(created.path, ['config', '--get', 'core.longpaths']).trim()).toBe('true');
+    } finally {
+      if (previousXdgDataHome === undefined) {
+        delete process.env.XDG_DATA_HOME;
+      } else {
+        process.env.XDG_DATA_HOME = previousXdgDataHome;
+      }
+    }
+  });
+
+  it('populateWorktreeWithLockRecovery enables longpaths before reset', async () => {
+    if (!canRunGit()) return;
+
+    const repo = createTempDir();
+    runGit(repo, ['init', '-b', 'main']);
+    runGit(repo, ['config', 'user.email', 'test@example.com']);
+    runGit(repo, ['config', 'user.name', 'Test User']);
+    fs.writeFileSync(path.join(repo, 'README.md'), '# Test\n');
+    runGit(repo, ['add', 'README.md']);
+    runGit(repo, ['commit', '-qm', 'init']);
+
+    const worktree = createTempDir();
+    fs.rmSync(worktree, { recursive: true, force: true });
+    runGit(repo, ['worktree', 'add', '--no-checkout', '-b', 'feature/longpaths-populate', worktree, 'HEAD']);
+
+    await expect(populateWorktreeWithLockRecovery(worktree)).resolves.toBeUndefined();
+    expect(runGit(worktree, ['config', '--get', 'core.longpaths']).trim()).toBe('true');
+    expect(fs.readFileSync(path.join(worktree, 'README.md'), 'utf8')).toBe('# Test\n');
+  });
+});
diff --git a/packages/web/server/lib/git/service.js b/packages/web/server/lib/git/service.js
index bd790acb..04baa715 100644
--- a/packages/web/server/lib/git/service.js
+++ b/packages/web/server/lib/git/service.js
@@ -991,34 +991,70 @@ const getFileIdentity = async (filePath) => {
   }
 };
 
+// OpenChamber places managed worktrees under a deep data-dir path
+// (`<XDG_DATA_HOME>/opencode/worktree/<40-char project id>/<name>/`). On
+// Windows that prefix plus a deeply nested repo file routinely exceeds
+// MAX_PATH (260). Git can check those paths out when core.longpaths is
+// enabled; without it, `git reset --hard` during bootstrap fails with
+// "Filename too long" and leaves a half-populated worktree (issue #2746).
+const WORKTREE_POPULATE_RESET_ARGS = ['-c', 'core.longpaths=true', 'reset', '--hard'];
+
+const isFilenameTooLongError = (message) => /file ?name too long/i.test(String(message || ''));
+
+const formatWorktreePopulateError = (message) => {
+  const text = String(message || '').trim() || 'Failed to populate worktree';
+  if (!isFilenameTooLongError(text)) {
+    return text;
+  }
+  return [
+    text,
+    'The worktree checkout path exceeds this system\'s path-length limit.',
+    'OpenChamber enables Git `core.longpaths` for worktree population; if this still fails on Windows, enable OS long paths (LongPathsEnabled) or open the repository from a shorter absolute path.',
+  ].join('\n');
+};
+
+export const ensureWorktreeLongpaths = async (directory) => {
+  const current = await runGitCommand(directory, ['config', '--get', 'core.longpaths']);
+  if (String(current.stdout || '').trim().toLowerCase() === 'true') {
+    return;
+  }
+  // Local config is shared across linked worktrees via the common git dir, so
+  // subsequent OpenChamber and CLI git operations in this repo also get long
+  // path support. Failures here are non-fatal: populate still passes
+  // `-c core.longpaths=true` on reset.
+  await runGitCommand(directory, ['config', 'core.longpaths', 'true']);
+};
+
 export const populateWorktreeWithLockRecovery = async (directory) => {
-  let result = await runGitCommand(directory, ['reset', '--hard']);
+  await ensureWorktreeLongpaths(directory);
+
+  let result = await runGitCommand(directory, WORKTREE_POPULATE_RESET_ARGS);
   if (result.success) {
     return;
   }
   if (!isIndexLockError(result)) {
-    throw new Error(result.message || 'Failed to populate worktree');
+    throw new Error(formatWorktreePopulateError(result.message));
   }
 
   await wait(WORKTREE_INDEX_LOCK_RETRY_DELAY_MS);
-  result = await runGitCommand(directory, ['reset', '--hard']);
+  result = await runGitCommand(directory, WORKTREE_POPULATE_RESET_ARGS);
   if (result.success) {
     return;
   }
   if (!isIndexLockError(result)) {
-    throw new Error(result.message || 'Failed to populate worktree');
+    throw new Error(formatWorktreePopulateError(result.message));
   }
 
   const lockPath = await getWorktreeIndexLockPath(directory);
   const identity = lockPath ? await getFileIdentity(lockPath) : null;
   await wait(WORKTREE_INDEX_LOCK_STALE_DELAY_MS);
 
-  result = await runGitCommand(directory, ['reset', '--hard']);
+  result = await runGitCommand(directory, WORKTREE_POPULATE_RESET_ARGS);
   if (result.success) {
     return;
   }
   if (!isIndexLockError(result) || !lockPath || !identity || await getFileIdentity(lockPath) !== identity) {
-    throw new Error(result.message || 'Failed to populate worktree');
+    throw new Error(formatWorktreePopulateError(result.message));
   }
 
   await fsp.unlink(lockPath).catch((error) => {
@@ -1026,7 +1062,10 @@ export const populateWorktreeWithLockRecovery = async (directory) => {
       throw error;
     }
   });
-  await runGitCommandOrThrow(directory, ['reset', '--hard'], 'Failed to populate worktree');
+  const finalResult = await runGitCommand(directory, WORKTREE_POPULATE_RESET_ARGS);
+  if (!finalResult.success) {
+    throw new Error(formatWorktreePopulateError(finalResult.message || 'Failed to populate worktree'));
+  }
 };
 
 // Worktrees are created with `git worktree add --no-checkout` and populated