feat(codex): tell Windows users once that Codex in Orca now shares ~/.codex (#24916)

* feat(codex): tell Windows users once what stays behind when Codex moves onto ~/.codex

When Windows' system-default Codex first runs on ~/.codex (launch prep or
the usage poll), main decides once whether Orca's managed home was ever
used and which MCP servers lived only there, and persists that in UI
state. The renderer shows one dismissible toast when a Codex terminal
exists, after the server-isolation notice rather than on top of it, and
clears the notice when shown.

The "kept only in the managed home" MCP rule is extracted into
isRuntimeOnlyMcpServer, which the config mirror merge now uses too, so
the notice names exactly the servers the mirror would have kept.

* fix(codex): stop counting Orca's own config.toml as use of the old Codex home

Orca's hook install writes that home's config.toml on every startup, so its
presence was true for nearly every Windows user with Codex. The home now
counts as used only with recorded sessions or an MCP server of its own.
Resolver tests keep one case per input source.

* refactor(codex): ask main for the shared-settings notice instead of persisting it

The persisted missing/object/null field, written from launch prep and the
usage poll, becomes a plain codexSharedSettingsNoticeSeen flag mirroring
codexTerminalServerIsolationNoticeSeen. When a Codex terminal first appears
and the flag is unset, the renderer asks codexConfigSync:sharedSettingsNotice
once; main answers read-only (Windows, system default on ~/.codex, managed
home path without mkdir) and maps any read error to null.

Runtime-home routing, launch and the test harness return to main's code.
The notice no longer waits for the server-isolation toast; they may stack.
The Codex-terminal watch moves to codex-terminal-presence.ts.

* refactor(codex): watch for the first Codex terminal in one place for both notices

The server-isolation notice now passes its due check to
whenCodexTerminalAppears instead of keeping its own copy of the presence
scan, input filter and subscription loop. Its behaviour and tests are
unchanged.

* docs(codex): trim isRuntimeOnlyMcpServer's comment to why it is shared

* refactor(codex): keep McpServerTomlOwnership private to its module

* test(codex): cover the shared-settings notice channel without type assertions

Handlers are looked up by channel now that two are registered, so the
status tests no longer depend on registration order.

* refactor(codex): show the Windows shared-settings notice without asking main

Every way of detecting who relied on Orca's old Codex folder had false
positives, so the renderer now shows one static toast on Windows the first
time a Codex terminal exists. This drops the main-process resolver, its IPC
channel, preload line, web stub and shared type, and the MCP-names variant
of the description.

* refactor(codex): restore the MCP server ownership helpers to main's shape

The static notice no longer reads MCP servers, so the shared
isRuntimeOnlyMcpServer extraction has no second caller.

* refactor(codex): let each notice decide when it is due, so the Codex watcher only watches

The isolation notice now selects its due predicate and starts the watcher only while due, so whenCodexTerminalAppears no longer takes an isDue or re-checks hydration and settings. The shared-settings notice uses isLocalWindowsDesktopClient, its test stubs the user agent instead of mocking pane-helpers, and the hydration safeguard it relies on is now tested on the UI slice itself.

* test(codex): drive the Codex notices through a reactive store, and drop a redundant hydration gate

The server-isolation notice now reads "is it due" through a store selector, but its test
mocked the store without re-rendering, so a due change after mount (persisted UI loading,
the setting turning off) was never exercised. The notice tests now share one harness backed
by a real zustand store, the shared watcher gets its own test, and both notices cover the
seen flag loading after mount.

persistedUIReady is dropped from isNoticeDue: the seen flag defaults to true and only
hydration clears it, in the same update that sets persistedUIReady. Both notices now gate
the same way.

* fix(codex): keep the shared-settings toast until dismissed, and shorten it

It is marked seen before it shows, so a 15s auto-close could lose it for good while the user
is typing in the Codex terminal that triggered it. Every other one-shot notice that marks
itself seen on show stays until dismissed; this now does too.

The text drops the sentence that repeated the title and keeps only what to expect and do.

---------

Co-authored-by: Orca Worker <orca-worker@localhost>

src/renderer/src/app-shell/use-app-shell-services.ts

@@ -21,6 +21,7 @@ import { useRemoteRuntimeRecoveryTriggers } from '../runtime/use-remote-runtime-
 import { useTerminalViewerColorPublication } from './use-terminal-viewer-color-publication'
 import { useBrowserIdentityMigrationNotice } from '../components/browser-pane/browser-user-agent-migration-notice'
 import { useCodexTerminalServerIsolationNotice } from '../components/terminal-pane/codex-terminal-server-isolation-notice'
+import { useCodexSharedSettingsNotice } from '../components/terminal-pane/codex-shared-settings-notice'
 
 /**
  * App-level subscriptions that must outlive any individual surface. Each one is here because
@@ -56,4 +57,5 @@ export function useAppShellServices(options: { floatingPanelVisible: boolean }):
   useOsc52ClipboardDefaultOnNotice(persistedUIReady)
   useBrowserIdentityMigrationNotice()
   useCodexTerminalServerIsolationNotice()
+  useCodexSharedSettingsNotice()
 }

src/renderer/src/components/terminal-pane/codex-notice-test-harness.ts

@@ -0,0 +1,37 @@
+import { act, createElement } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { useStore } from 'zustand'
+import { createStore } from 'zustand/vanilla'
+
+type NoticeTestState = Record<string, unknown>
+
+/** Stands in for `@/store`: a real zustand store, so selectors re-render and subscribe fires. */
+export const noticeTestStore = createStore<NoticeTestState>()(() => ({}))
+
+export const useAppStore = Object.assign(
+  <T>(selector: (state: NoticeTestState) => T): T => useStore(noticeTestStore, selector),
+  noticeTestStore
+)
+
+const mountedRoots: Root[] = []
+
+export async function mountHook(useHook: () => void): Promise<void> {
+  function HookProbe(): null {
+    useHook()
+    return null
+  }
+  const root = createRoot(document.createElement('div'))
+  mountedRoots.push(root)
+  await act(async () => root.render(createElement(HookProbe)))
+}
+
+export function unmountHooks(): void {
+  for (const root of mountedRoots.splice(0)) {
+    act(() => root.unmount())
+  }
+}
+
+/** Applies a store write and lets the hook re-render before returning. */
+export async function setNoticeState(patch: NoticeTestState): Promise<void> {
+  await act(async () => noticeTestStore.setState(patch))
+}

src/renderer/src/components/terminal-pane/codex-shared-settings-notice.test.ts

@@ -0,0 +1,89 @@
+// @vitest-environment happy-dom
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  mountHook,
+  noticeTestStore,
+  setNoticeState,
+  unmountHooks
+} from './codex-notice-test-harness'
+import { useCodexSharedSettingsNotice } from './codex-shared-settings-notice'
+
+const { toastInfoMock } = vi.hoisted(() => ({ toastInfoMock: vi.fn() }))
+
+vi.mock('sonner', () => ({ toast: { info: toastInfoMock } }))
+vi.mock('@/store', () => import('./codex-notice-test-harness'))
+
+const codexTab = { 'wt-1': [{ id: 'tab-1', launchAgent: 'codex' }] }
+
+function resetStore(overrides: Record<string, unknown> = {}): void {
+  noticeTestStore.setState(
+    {
+      codexSharedSettingsNoticeSeen: false,
+      tabsByWorktree: {},
+      agentStatusByPaneKey: {},
+      paneForegroundAgentByPaneKey: {},
+      markCodexSharedSettingsNoticeSeen: () =>
+        noticeTestStore.setState({ codexSharedSettingsNoticeSeen: true }),
+      ...overrides
+    },
+    true
+  )
+}
+
+const isSeen = (): unknown => noticeTestStore.getState().codexSharedSettingsNoticeSeen
+
+describe('useCodexSharedSettingsNotice', () => {
+  beforeEach(() => {
+    toastInfoMock.mockReset()
+    vi.stubGlobal('navigator', { userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64)' })
+    resetStore()
+  })
+
+  afterEach(() => {
+    unmountHooks()
+    vi.unstubAllGlobals()
+  })
+
+  it('shows once on Windows when a Codex terminal appears, and marks it seen', async () => {
+    await mountHook(useCodexSharedSettingsNotice)
+    expect(toastInfoMock).not.toHaveBeenCalled()
+
+    await setNoticeState({ tabsByWorktree: codexTab })
+    await setNoticeState({ agentStatusByPaneKey: { 'tab-1:leaf': { agentType: 'codex' } } })
+
+    expect(toastInfoMock).toHaveBeenCalledTimes(1)
+    expect(toastInfoMock).toHaveBeenCalledWith('Codex in Orca now uses ~/.codex', {
+      id: 'codex-shared-settings-notice',
+      description:
+        'Codex may ask again to trust folders or approve commands. Re-add any MCP servers you added only in Orca.',
+      duration: Infinity
+    })
+    expect(isSeen()).toBe(true)
+  })
+
+  it('stays quiet off Windows', async () => {
+    vi.stubGlobal('navigator', { userAgent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)' })
+    resetStore({ tabsByWorktree: codexTab })
+    await mountHook(useCodexSharedSettingsNotice)
+    expect(toastInfoMock).not.toHaveBeenCalled()
+    expect(isSeen()).toBe(false)
+  })
+
+  it('stays quiet in a paired web client window', async () => {
+    vi.stubGlobal('__ORCA_WEB_CLIENT__', true)
+    resetStore({ tabsByWorktree: codexTab })
+    await mountHook(useCodexSharedSettingsNotice)
+    expect(toastInfoMock).not.toHaveBeenCalled()
+  })
+
+  it('shows once the persisted seen flag loads after mount', async () => {
+    // Why seen: true: the store's default until persisted UI arrives.
+    resetStore({ codexSharedSettingsNoticeSeen: true, tabsByWorktree: codexTab })
+    await mountHook(useCodexSharedSettingsNotice)
+    expect(toastInfoMock).not.toHaveBeenCalled()
+
+    await setNoticeState({ codexSharedSettingsNoticeSeen: false })
+    expect(toastInfoMock).toHaveBeenCalledTimes(1)
+  })
+})

src/renderer/src/components/terminal-pane/codex-shared-settings-notice.ts

@@ -0,0 +1,37 @@
+import { useEffect } from 'react'
+import { toast } from 'sonner'
+import { translate } from '@/i18n/i18n'
+import { useAppStore } from '@/store'
+import { isLocalWindowsDesktopClient } from '@/lib/desktop-window-chrome'
+import { whenCodexTerminalAppears } from './codex-terminal-presence'
+
+function showCodexSharedSettingsNotice(): void {
+  // Why mark before showing: seen means shown, so a quit or reload never repeats it.
+  useAppStore.getState().markCodexSharedSettingsNoticeSeen()
+  toast.info(
+    translate('terminal.codexSharedSettingsNotice.title', 'Codex in Orca now uses ~/.codex'),
+    {
+      // Why a stable id: a late sync that resets the flag can't stack a second toast.
+      id: 'codex-shared-settings-notice',
+      description: translate(
+        'terminal.codexSharedSettingsNotice.description',
+        'Codex may ask again to trust folders or approve commands. Re-add any MCP servers you added only in Orca.'
+      ),
+      // Why no timeout: it is marked seen before showing, so an auto-close would lose it for good.
+      duration: Infinity
+    }
+  )
+}
+
+export function useCodexSharedSettingsNotice(): void {
+  // Why no hydration check: the flag defaults to true until the persisted value arrives.
+  const seen = useAppStore((s) => s.codexSharedSettingsNoticeSeen)
+
+  useEffect(() => {
+    // Why skip paired web clients: the change is on the host, whose own window shows this.
+    if (seen || !isLocalWindowsDesktopClient()) {
+      return
+    }
+    return whenCodexTerminalAppears(showCodexSharedSettingsNotice)
+  }, [seen])
+}

src/renderer/src/components/terminal-pane/codex-terminal-presence.test.ts

@@ -0,0 +1,56 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { noticeTestStore } from './codex-notice-test-harness'
+import { whenCodexTerminalAppears } from './codex-terminal-presence'
+
+vi.mock('@/store', () => import('./codex-notice-test-harness'))
+
+describe('whenCodexTerminalAppears', () => {
+  beforeEach(() => {
+    noticeTestStore.setState(
+      { tabsByWorktree: {}, agentStatusByPaneKey: {}, paneForegroundAgentByPaneKey: {} },
+      true
+    )
+  })
+
+  it.each([
+    ['an Orca-launched Codex tab', { tabsByWorktree: { 'wt-1': [{ launchAgent: 'codex' }] } }],
+    ['a hook-reported Codex', { agentStatusByPaneKey: { 'tab-1:leaf': { agentType: 'codex' } } }],
+    [
+      'a typed codex in the foreground',
+      { paneForegroundAgentByPaneKey: { 'tab-1:leaf': { agent: 'codex' } } }
+    ]
+  ])('calls back once for %s', (_name, patch) => {
+    const onAppear = vi.fn()
+    whenCodexTerminalAppears(onAppear)
+
+    noticeTestStore.setState(patch)
+    noticeTestStore.setState({ tabsByWorktree: { 'wt-2': [{ launchAgent: 'codex' }] } })
+
+    expect(onAppear).toHaveBeenCalledTimes(1)
+  })
+
+  it('calls back at once when a Codex terminal already exists', () => {
+    noticeTestStore.setState({ tabsByWorktree: { 'wt-1': [{ launchAgent: 'codex' }] } })
+    const onAppear = vi.fn()
+    whenCodexTerminalAppears(onAppear)
+    expect(onAppear).toHaveBeenCalledTimes(1)
+  })
+
+  it('ignores other agents', () => {
+    const onAppear = vi.fn()
+    whenCodexTerminalAppears(onAppear)
+    noticeTestStore.setState({
+      tabsByWorktree: { 'wt-1': [{ launchAgent: 'claude' }] },
+      agentStatusByPaneKey: { 'tab-1:leaf': { agentType: 'claude' } },
+      paneForegroundAgentByPaneKey: { 'tab-1:leaf': { agent: 'opencode' } }
+    })
+    expect(onAppear).not.toHaveBeenCalled()
+  })
+
+  it('stops watching once unsubscribed', () => {
+    const onAppear = vi.fn()
+    whenCodexTerminalAppears(onAppear)()
+    noticeTestStore.setState({ tabsByWorktree: { 'wt-1': [{ launchAgent: 'codex' }] } })
+    expect(onAppear).not.toHaveBeenCalled()
+  })
+})

src/renderer/src/components/terminal-pane/codex-terminal-presence.ts

@@ -0,0 +1,37 @@
+import { useAppStore } from '@/store'
+import type { AppState } from '@/store/types'
+
+// Why three sources: Orca-launched tabs, hook-reported agents (SSH too), and a typed `codex` seen locally.
+function hasCodexTerminal(state: AppState): boolean {
+  return (
+    Object.values(state.tabsByWorktree).some((tabs) =>
+      tabs.some((tab) => tab.launchAgent === 'codex')
+    ) ||
+    Object.values(state.agentStatusByPaneKey).some((entry) => entry.agentType === 'codex') ||
+    Object.values(state.paneForegroundAgentByPaneKey).some((entry) => entry.agent === 'codex')
+  )
+}
+
+function didSourcesChange(state: AppState, previous: AppState): boolean {
+  return (
+    state.tabsByWorktree !== previous.tabsByWorktree ||
+    state.agentStatusByPaneKey !== previous.agentStatusByPaneKey ||
+    state.paneForegroundAgentByPaneKey !== previous.paneForegroundAgentByPaneKey
+  )
+}
+
+/** Calls `onAppear` once, as soon as a Codex terminal exists. Returns the unsubscribe. */
+export function whenCodexTerminalAppears(onAppear: () => void): () => void {
+  if (hasCodexTerminal(useAppStore.getState())) {
+    onAppear()
+    return () => {}
+  }
+  // Why a filtered subscription: a selector would rescan every tab on each store write.
+  const unsubscribe = useAppStore.subscribe((state, previous) => {
+    if (didSourcesChange(state, previous) && hasCodexTerminal(state)) {
+      unsubscribe()
+      onAppear()
+    }
+  })
+  return unsubscribe
+}

src/renderer/src/components/terminal-pane/codex-terminal-server-isolation-notice.test.ts

@@ -1,43 +1,27 @@
 // @vitest-environment happy-dom
 
-import { act, createElement } from 'react'
-import { createRoot, type Root } from 'react-dom/client'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { CODEX_TERMINAL_SERVER_ISOLATION_SETTINGS_TARGET_ID } from '@/lib/settings-navigation-types'
+import {
+  mountHook,
+  noticeTestStore,
+  setNoticeState,
+  unmountHooks
+} from './codex-notice-test-harness'
 import { useCodexTerminalServerIsolationNotice } from './codex-terminal-server-isolation-notice'
 
-// Why a real zustand store double: the hook relies on subscribe/setState semantics.
-const { toastInfoMock, harness } = vi.hoisted(() => ({
-  toastInfoMock: vi.fn(),
-  harness: { setState: (_patch: Record<string, unknown>, _replace?: true): void => {} }
-}))
+const { toastInfoMock } = vi.hoisted(() => ({ toastInfoMock: vi.fn() }))
 
 vi.mock('sonner', () => ({ toast: { info: toastInfoMock } }))
-
-vi.mock('@/store', async () => {
-  const { createStore } = await import('zustand/vanilla')
-  const backing = createStore<Record<string, unknown>>()(() => ({}))
-  harness.setState = (patch, replace) =>
-    replace ? backing.setState(patch, true) : backing.setState(patch)
-  const useAppStore = <T>(selector: (state: Record<string, unknown>) => T): T =>
-    selector(backing.getState())
-  return { useAppStore: Object.assign(useAppStore, backing) }
-})
-
-const store = {
-  setState: (patch: Record<string, unknown>, replace?: true) => harness.setState(patch, replace)
-}
-let seen = false
+vi.mock('@/store', () => import('./codex-notice-test-harness'))
 
 const openSettingsPage = vi.fn()
 const openSettingsTarget = vi.fn()
-const mountedRoots: Root[] = []
+const codexTab = { 'wt-1': [{ id: 'tab-1', launchAgent: 'codex' }] }
 
 function resetStore(overrides: Record<string, unknown> = {}): void {
-  seen = false
-  store.setState(
+  noticeTestStore.setState(
     {
-      persistedUIReady: true,
       codexTerminalServerIsolationNoticeSeen: false,
       settings: { codexTerminalServerIsolation: true },
       tabsByWorktree: {},
@@ -45,33 +29,14 @@ function resetStore(overrides: Record<string, unknown> = {}): void {
       paneForegroundAgentByPaneKey: {},
       openSettingsPage,
       openSettingsTarget,
-      markCodexTerminalServerIsolationNoticeSeen: () => {
-        seen = true
-        store.setState({ codexTerminalServerIsolationNoticeSeen: true })
-      },
+      markCodexTerminalServerIsolationNoticeSeen: () =>
+        noticeTestStore.setState({ codexTerminalServerIsolationNoticeSeen: true }),
       ...overrides
     },
     true
   )
 }
 
-function HookProbe(): null {
-  useCodexTerminalServerIsolationNotice()
-  return null
-}
-
-async function mountProbe(): Promise<void> {
-  const container = document.createElement('div')
-  document.body.appendChild(container)
-  const root = createRoot(container)
-  mountedRoots.push(root)
-  await act(async () => {
-    root.render(createElement(HookProbe))
-  })
-}
-
-const codexTab = { 'wt-1': [{ id: 'tab-1', launchAgent: 'codex' }] }
-
 describe('useCodexTerminalServerIsolationNotice', () => {
   beforeEach(() => {
     toastInfoMock.mockReset()
@@ -80,65 +45,50 @@ describe('useCodexTerminalServerIsolationNotice', () => {
     resetStore()
   })
 
-  afterEach(() => {
-    for (const root of mountedRoots.splice(0)) {
-      act(() => root.unmount())
-    }
-    document.body.innerHTML = ''
-  })
+  afterEach(unmountHooks)
 
   it('shows once when the first Codex terminal starts, and marks it seen', async () => {
-    await mountProbe()
+    await mountHook(useCodexTerminalServerIsolationNotice)
     expect(toastInfoMock).not.toHaveBeenCalled()
 
-    act(() => store.setState({ tabsByWorktree: codexTab }))
-    act(() => store.setState({ agentStatusByPaneKey: { 'tab-2:leaf': { agentType: 'codex' } } }))
+    await setNoticeState({ tabsByWorktree: codexTab })
+    await setNoticeState({ agentStatusByPaneKey: { 'tab-2:leaf': { agentType: 'codex' } } })
 
     expect(toastInfoMock).toHaveBeenCalledTimes(1)
     expect(toastInfoMock.mock.calls[0]?.[1]).toMatchObject({ duration: Infinity })
-    expect(seen).toBe(true)
-  })
-
-  it.each([
-    [
-      'a typed codex seen by hooks',
-      { agentStatusByPaneKey: { 'tab-1:leaf': { agentType: 'codex' } } }
-    ],
-    [
-      'a typed codex in the foreground',
-      { paneForegroundAgentByPaneKey: { 'tab-1:leaf': { agent: 'codex' } } }
-    ]
-  ])('also triggers on %s', async (_name, patch) => {
-    await mountProbe()
-    act(() => store.setState(patch))
-    expect(toastInfoMock).toHaveBeenCalledTimes(1)
-  })
-
-  it('never shows for other agents', async () => {
-    await mountProbe()
-    act(() =>
-      store.setState({
-        tabsByWorktree: { 'wt-1': [{ id: 'tab-1', launchAgent: 'claude' }] },
-        agentStatusByPaneKey: { 'tab-1:leaf': { agentType: 'claude' } },
-        paneForegroundAgentByPaneKey: { 'tab-1:leaf': { agent: 'opencode' } }
-      })
-    )
-    expect(toastInfoMock).not.toHaveBeenCalled()
+    expect(noticeTestStore.getState().codexTerminalServerIsolationNoticeSeen).toBe(true)
   })
 
   it.each([
     ['it was already seen', { codexTerminalServerIsolationNoticeSeen: true }],
     ['the user turned the setting off', { settings: { codexTerminalServerIsolation: false } }],
-    ['persisted UI has not hydrated', { persistedUIReady: false }]
+    ['settings have not loaded', { settings: null }]
   ])('stays quiet when %s', async (_name, overrides) => {
     resetStore({ ...overrides, tabsByWorktree: codexTab })
-    await mountProbe()
+    await mountHook(useCodexTerminalServerIsolationNotice)
+    expect(toastInfoMock).not.toHaveBeenCalled()
+  })
+
+  it('shows once the persisted seen flag loads after mount', async () => {
+    // Why seen: true: the store's default until persisted UI arrives.
+    resetStore({ codexTerminalServerIsolationNoticeSeen: true, tabsByWorktree: codexTab })
+    await mountHook(useCodexTerminalServerIsolationNotice)
+    expect(toastInfoMock).not.toHaveBeenCalled()
+
+    await setNoticeState({ codexTerminalServerIsolationNoticeSeen: false })
+    expect(toastInfoMock).toHaveBeenCalledTimes(1)
+  })
+
+  it('stops waiting when the user turns the setting off', async () => {
+    await mountHook(useCodexTerminalServerIsolationNotice)
+    await setNoticeState({ settings: { codexTerminalServerIsolation: false } })
+    await setNoticeState({ tabsByWorktree: codexTab })
     expect(toastInfoMock).not.toHaveBeenCalled()
   })
 
   it('opens Settings at the Codex server setting', async () => {
     resetStore({ tabsByWorktree: codexTab })
-    await mountProbe()
+    await mountHook(useCodexTerminalServerIsolationNotice)
 
     toastInfoMock.mock.calls[0]?.[1]?.action.onClick()
 

src/renderer/src/components/terminal-pane/codex-terminal-server-isolation-notice.ts

@@ -6,46 +6,15 @@ import type { AppState } from '@/store/types'
 import { isPairedWebClientWindow } from '@/lib/desktop-window-chrome'
 import { CODEX_TERMINAL_SERVER_ISOLATION_SETTINGS_TARGET_ID } from '@/lib/settings-navigation-types'
 import { isCodexTerminalServerIsolationEnabled } from '../../../../shared/codex-terminal-server-isolation'
+import { whenCodexTerminalAppears } from './codex-terminal-presence'
 
-type CodexNoticeState = Pick<
-  AppState,
-  | 'persistedUIReady'
-  | 'codexTerminalServerIsolationNoticeSeen'
-  | 'settings'
-  | 'tabsByWorktree'
-  | 'agentStatusByPaneKey'
-  | 'paneForegroundAgentByPaneKey'
->
-
-// Why three sources: Orca-launched tabs, hook-reported agents (SSH too), and a typed `codex` seen locally.
-function hasCodexTerminal(state: CodexNoticeState): boolean {
+// Why no hydration check: the seen flag defaults to true until the persisted value arrives.
+function isNoticeDue(state: AppState): boolean {
   return (
-    Object.values(state.tabsByWorktree).some((tabs) =>
-      tabs.some((tab) => tab.launchAgent === 'codex')
-    ) ||
-    Object.values(state.agentStatusByPaneKey).some((entry) => entry.agentType === 'codex') ||
-    Object.values(state.paneForegroundAgentByPaneKey).some((entry) => entry.agent === 'codex')
-  )
-}
-
-export function shouldShowCodexTerminalServerIsolationNotice(state: CodexNoticeState): boolean {
-  return (
-    state.persistedUIReady &&
     !state.codexTerminalServerIsolationNoticeSeen &&
     state.settings !== null &&
     // Why: a user who already opted out needs no announcement of the default.
-    isCodexTerminalServerIsolationEnabled(state.settings) &&
-    hasCodexTerminal(state)
-  )
-}
-
-function didNoticeInputsChange(state: CodexNoticeState, previous: CodexNoticeState): boolean {
-  return (
-    state.persistedUIReady !== previous.persistedUIReady ||
-    state.settings !== previous.settings ||
-    state.tabsByWorktree !== previous.tabsByWorktree ||
-    state.agentStatusByPaneKey !== previous.agentStatusByPaneKey ||
-    state.paneForegroundAgentByPaneKey !== previous.paneForegroundAgentByPaneKey
+    isCodexTerminalServerIsolationEnabled(state.settings)
   )
 }
 
@@ -93,27 +62,13 @@ function showCodexTerminalServerIsolationNotice(): void {
 }
 
 export function useCodexTerminalServerIsolationNotice(): void {
-  const seen = useAppStore((s) => s.codexTerminalServerIsolationNoticeSeen)
+  const due = useAppStore(isNoticeDue)
 
   useEffect(() => {
     // Why: a paired web client's terminals follow the host's setting, not this window's.
-    if (seen || isPairedWebClientWindow()) {
+    if (!due || isPairedWebClientWindow()) {
       return
     }
-    if (shouldShowCodexTerminalServerIsolationNotice(useAppStore.getState())) {
-      showCodexTerminalServerIsolationNotice()
-      return
-    }
-    // Why a filtered subscription: a selector would rescan every tab on each store write.
-    const unsubscribe = useAppStore.subscribe((state, previous) => {
-      if (
-        didNoticeInputsChange(state, previous) &&
-        shouldShowCodexTerminalServerIsolationNotice(state)
-      ) {
-        unsubscribe()
-        showCodexTerminalServerIsolationNotice()
-      }
-    })
-    return unsubscribe
-  }, [seen])
+    return whenCodexTerminalAppears(showCodexTerminalServerIsolationNotice)
+  }, [due])
 }

src/renderer/src/i18n/locales/en.json

@@ -18755,6 +18755,10 @@
       "description": "This makes agent status more reliable. You can turn it back on in Settings.",
       "openSettings": "Open Settings"
     },
+    "codexSharedSettingsNotice": {
+      "title": "Codex in Orca now uses ~/.codex",
+      "description": "Codex may ask again to trust folders or approve commands. Re-add any MCP servers you added only in Orca."
+    },
     "codexSharedServerBanner": {
       "title": "This Codex is sharing a server with your other Codex tabs",
       "body": "Sessions may end unexpectedly, and agent status may be wrong.",

src/renderer/src/store/slices/ui-notice-dismissals.test.ts

@@ -251,6 +251,19 @@ describe('createUISlice browser import hint dismissal', () => {
   })
 })
 
+describe('createUISlice Codex shared-settings notice', () => {
+  it('counts as seen until hydration, then follows the persisted flag', () => {
+    const store = createUIStore()
+    expect(store.getState().codexSharedSettingsNoticeSeen).toBe(true)
+
+    store.getState().hydratePersistedUI(makePersistedUI({}))
+    expect(store.getState().codexSharedSettingsNoticeSeen).toBe(false)
+
+    store.getState().hydratePersistedUI(makePersistedUI({ codexSharedSettingsNoticeSeen: true }))
+    expect(store.getState().codexSharedSettingsNoticeSeen).toBe(true)
+  })
+})
+
 describe('createUISlice clearOsc52ClipboardDefaultOnNotice', () => {
   it('restores the armed notice from persisted UI', () => {
     const store = createUIStore()

src/renderer/src/store/slices/ui/ui-slice-contract-contextual.ts

@@ -116,4 +116,6 @@ export type UISliceContextual = {
   dismissUsageEmptyState: () => void
   codexTerminalServerIsolationNoticeSeen: boolean
   markCodexTerminalServerIsolationNoticeSeen: () => void
+  codexSharedSettingsNoticeSeen: boolean
+  markCodexSharedSettingsNoticeSeen: () => void
 }

src/renderer/src/store/slices/ui/ui-slice-hydration-actions.ts

@@ -244,6 +244,7 @@ export function createUiHydrationActions(set: UISliceSet, _get: UISliceGet): Par
           usageEmptyStateDismissed: ui.usageEmptyStateDismissed === true,
           codexTerminalServerIsolationNoticeSeen:
             ui.codexTerminalServerIsolationNoticeSeen === true,
+          codexSharedSettingsNoticeSeen: ui.codexSharedSettingsNoticeSeen === true,
           ...hydrateAgentReadState(ui),
           workspaceCleanupDismissals: sanitizeWorkspaceCleanupDismissals(
             ui.workspaceCleanup?.dismissals

src/renderer/src/store/slices/ui/ui-slice-trust-actions.ts

@@ -148,6 +148,15 @@ export function createUiTrustActions(set: UISliceSet, _get: UISliceGet): Partial
         }
         window.api.ui.set({ codexTerminalServerIsolationNoticeSeen: true }).catch(console.error)
         return { codexTerminalServerIsolationNoticeSeen: true }
+      }),
+    codexSharedSettingsNoticeSeen: true,
+    markCodexSharedSettingsNoticeSeen: () =>
+      set((s) => {
+        if (s.codexSharedSettingsNoticeSeen) {
+          return s
+        }
+        window.api.ui.set({ codexSharedSettingsNoticeSeen: true }).catch(console.error)
+        return { codexSharedSettingsNoticeSeen: true }
       })
   }
 }

src/shared/persisted-ui-state-types.ts

@@ -172,6 +172,8 @@ export type PersistedUIState = {
   usageEmptyStateDismissed?: boolean
   /** One-shot toast announcing per-terminal Codex servers; set when shown, so absent means not yet seen. */
   codexTerminalServerIsolationNoticeSeen?: boolean
+  /** Windows one-shot toast for Codex moving onto ~/.codex; set when shown, so absent means not yet seen. */
+  codexSharedSettingsNoticeSeen?: boolean
   /** URL for new browser tabs; null = blank tab. */
   browserDefaultUrl?: string | null
   browserDefaultSearchEngine?: 'google' | 'duckduckgo' | 'bing' | 'kagi' | null

src/shared/rpc-contract/client-ui-params.ts

@@ -239,6 +239,7 @@ export const UiUpdateFields = z
     usagePercentageDisplayChangeNoticeDismissed: z.boolean().optional(),
     usageEmptyStateDismissed: z.boolean().optional(),
     codexTerminalServerIsolationNoticeSeen: z.boolean().optional(),
+    codexSharedSettingsNoticeSeen: z.boolean().optional(),
     petVisible: z.boolean().optional(),
     petId: z.string().optional(),
     customPets: UnknownRecordArray.optional(),