From 2c762c9b3ebdc6ce8116c97809ad85c68d04a33a Mon Sep 17 00:00:00 2001
From: Anton Frehser <hey@tonyfresher.com>
Date: Tue, 6 Oct 2026 19:20:00 +0200
Subject: [PATCH 1/3] Open exact chats through workspace links

---
 client/features/chat/ChatPanel.tsx            |   4 +-
 .../chat/messages/MarkdownContent.test.tsx    |   3 +-
 client/features/chat/sessions/api.ts          |  12 +-
 client/features/chat/sessions/chat-link.ts    |  37 ++
 .../chat/sessions/useSelectedSession.ts       |  69 ++--
 client/features/workspace/WorkspaceScreen.tsx |   7 +-
 .../workspace/useWorkspaceNavigation.test.tsx | 350 ++++++++++++++++--
 .../workspace/useWorkspaceNavigation.ts       | 134 ++++++-
 docs/navigation.md                            |  23 +-
 lib/navigation.test.ts                        |  32 +-
 lib/navigation.ts                             |  34 +-
 server/control.ts                             |   7 +-
 server/test/navigation-cli.test.ts            |  59 +--
 13 files changed, 651 insertions(+), 120 deletions(-)
 create mode 100644 client/features/chat/sessions/chat-link.ts

diff --git a/client/features/chat/ChatPanel.tsx b/client/features/chat/ChatPanel.tsx
index 7a2f90b8..19c33278 100644
--- a/client/features/chat/ChatPanel.tsx
+++ b/client/features/chat/ChatPanel.tsx
@@ -3,7 +3,7 @@ import { Link } from 'wouter'
 
 import { IconArrowBackUp, IconChevronDown, IconChevronsRight, IconX } from '@tabler/icons-react'
 import { draftSessionId } from '@/lib/session-drafts'
-import { workspaceTabPath } from '@/lib/navigation'
+import { addressPath } from '@/lib/navigation'
 import { useCurrentTabId } from './sessions/useSelectedSession'
 
 import { canSubmitComposerAction, focusComposer } from '@/client/components/shared/Composer'
@@ -205,7 +205,7 @@ export function ChatPanel({
           <div className="mx-auto flex w-full max-w-(--chat-max-container) flex-1 flex-col gap-6">
             {forkedFromSessionId && (
               <Link
-                href={workspaceTabPath(workspaceId, 'overview')}
+                href={addressPath(workspaceId, { sessionId: forkedFromSessionId, search: '' })}
                 className="block text-sm outline-none focus-visible:ring-3 focus-visible:ring-ring/50"
               >
                 <div className="flex items-center gap-3">
diff --git a/client/features/chat/messages/MarkdownContent.test.tsx b/client/features/chat/messages/MarkdownContent.test.tsx
index 9a33cd67..fdd5d411 100644
--- a/client/features/chat/messages/MarkdownContent.test.tsx
+++ b/client/features/chat/messages/MarkdownContent.test.tsx
@@ -8,12 +8,13 @@ test('chat renders portable links as native workspace hrefs with the deployment
   const html = renderToStaticMarkup(
     <Router base="/prefix">
       <Workspace id="abc">
-        <MarkdownContent content="[Event](moi:/views/events?eventId=123) [Web](https://example.com/)" />
+        <MarkdownContent content="[Event](moi:/views/events?eventId=123) [Chat](moi:/chats/chat-1) [Web](https://example.com/)" />
       </Workspace>
     </Router>
   )
   expect(html).toContain('href="/prefix/workspace/abc/views/events?eventId=123"')
   expect(html).toContain('href="https://example.com/"')
+  expect(html).toContain('href="/prefix/workspace/abc/chats/chat-1"')
 })
 
 test('invalid moi links and executable URLs stay sanitized, including images', () => {
diff --git a/client/features/chat/sessions/api.ts b/client/features/chat/sessions/api.ts
index 7b030efb..7c8a0fa2 100644
--- a/client/features/chat/sessions/api.ts
+++ b/client/features/chat/sessions/api.ts
@@ -14,12 +14,16 @@ import type {
   WorkspaceSessionSelection
 } from '@/lib/types'
 
-export function useWorkspaceSessions(workspaceId: string) {
-  return useQuery<SessionInfo[]>({
+export function workspaceSessionsOptions(workspaceId: string) {
+  return {
     queryKey: workspaceKeys.sessions(workspaceId),
-    queryFn: () => requestJson(`/api/workspaces/${workspaceId}/sessions`),
+    queryFn: () => requestJson<SessionInfo[]>(`/api/workspaces/${workspaceId}/sessions`),
     ...WORKSPACE_RESOURCE_OPTIONS
-  })
+  }
+}
+
+export function useWorkspaceSessions(workspaceId: string) {
+  return useQuery(workspaceSessionsOptions(workspaceId))
 }
 
 export function removeArchivedSession(
diff --git a/client/features/chat/sessions/chat-link.ts b/client/features/chat/sessions/chat-link.ts
new file mode 100644
index 00000000..4256c539
--- /dev/null
+++ b/client/features/chat/sessions/chat-link.ts
@@ -0,0 +1,37 @@
+import type { QueryClient } from '@tanstack/react-query'
+import { workspaceKeys } from '@/client/api/workspace-keys'
+import { workspaceSessionsOptions } from './api'
+import { tabAvailable } from '@/client/features/workspace/tab-resolution'
+import { isWorkspaceTabId } from '@/lib/workspace-tabs'
+import type { SessionInfo, ViewInfo, WorkspaceTabId } from '@/lib/types'
+
+// Metadata alone does not establish existence: the sessions API combines the
+// harness's live chat list with moi's attribution records.
+export async function resolveChatLink(
+  queryClient: QueryClient,
+  workspaceId: string,
+  sessionId: string,
+  views: ViewInfo[],
+  signal: AbortSignal
+): Promise<WorkspaceTabId | null> {
+  signal.throwIfAborted()
+  let session = queryClient
+    .getQueryData<SessionInfo[]>(workspaceKeys.sessions(workspaceId))
+    ?.find(session => session.sessionId === sessionId)
+  if (!session) {
+    const sessions = await queryClient.fetchQuery(workspaceSessionsOptions(workspaceId))
+    session = sessions.find(session => session.sessionId === sessionId)
+  }
+  signal.throwIfAborted()
+  if (!session) return null
+  const tab = isWorkspaceTabId(session.tabId) ? session.tabId : 'overview'
+  if (!tabAvailable(tab, views)) {
+    await queryClient.refetchQueries(
+      { queryKey: workspaceKeys.views(workspaceId), exact: true },
+      { throwOnError: true }
+    )
+    signal.throwIfAborted()
+    views = queryClient.getQueryData<ViewInfo[]>(workspaceKeys.views(workspaceId)) ?? views
+  }
+  return tabAvailable(tab, views) ? tab : null
+}
diff --git a/client/features/chat/sessions/useSelectedSession.ts b/client/features/chat/sessions/useSelectedSession.ts
index 68412ce9..2560cdff 100644
--- a/client/features/chat/sessions/useSelectedSession.ts
+++ b/client/features/chat/sessions/useSelectedSession.ts
@@ -31,7 +31,8 @@ type SetSelectedSession = (sessionId: string | null) => void
 
 type SelectedSessionResult = readonly [
   sessionId: string | null | undefined,
-  setSessionId: SetSelectedSession
+  setSessionId: SetSelectedSession,
+  selectSessionForTab: (sessionId: string, tabId: WorkspaceTabId) => Promise<void>
 ]
 
 export type SelectedSessionSaveResult = 'applied' | 'conflict' | 'ignored'
@@ -41,6 +42,23 @@ export function selectedSessionKey(workspaceId: string, scope: SelectedSessionSc
   return scope === 'browser-tab' ? ([...key, 'browser-tab'] as const) : key
 }
 
+export function selectedSessionOptions(
+  workspaceId: string,
+  scope: SelectedSessionScope = 'shared'
+) {
+  return {
+    queryKey: selectedSessionKey(workspaceId, scope),
+    queryFn: () =>
+      scope === 'browser-tab'
+        ? Promise.resolve(readSelectedSession(workspaceId))
+        : requestJson<WorkspaceSessionSelection>(`/api/workspaces/${workspaceId}/selected-session`),
+    staleTime: Infinity,
+    gcTime: 0,
+    refetchOnMount: false,
+    refetchOnWindowFocus: false
+  }
+}
+
 function selectedSessionMutationKey(workspaceId: string, scope: SelectedSessionScope) {
   return [...selectedSessionKey(workspaceId, scope), 'save'] as const
 }
@@ -179,21 +197,11 @@ export function useSelectedSession(explicitTabId?: WorkspaceTabId): SelectedSess
   // WorkspaceContent remains an observer for the active workspace. Nested hook
   // users reuse its result without refetching; once the route unmounts, dropping
   // the cache makes the next visit load the server-owned selection again.
-  const query = useQuery<WorkspaceSessionSelection>({
-    queryKey,
-    queryFn: () =>
-      scope === 'browser-tab'
-        ? Promise.resolve(readSelectedSession(workspaceId))
-        : requestJson(`/api/workspaces/${workspaceId}/selected-session`),
-    staleTime: Infinity,
-    gcTime: 0,
-    refetchOnMount: false,
-    refetchOnWindowFocus: false
-  })
+  const query = useQuery(selectedSessionOptions(workspaceId, scope))
   // A pin is shared with CLI creation and applies to every workspace tab.
   const sharedSelection = useWorkspaceSessionSelection().data
 
-  const { mutate: saveSelectedSession } = useMutation<
+  const { mutate: saveSelectedSession, mutateAsync: saveSelectedSessionAsync } = useMutation<
     SelectedSessionState,
     Error,
     SaveSelectedSessionInput
@@ -253,6 +261,27 @@ export function useSelectedSession(explicitTabId?: WorkspaceTabId): SelectedSess
     [queryClient, saveSelectedSession, workspaceId, tabId, scope]
   )
 
+  const selectSessionForTab = useCallback(
+    async (sessionId: string, destination: WorkspaceTabId) => {
+      const input = optimisticallySetSelectedSession(
+        queryClient,
+        workspaceId,
+        sessionId,
+        destination,
+        scope
+      )
+      if (!input) return
+      const saved = await saveSelectedSessionAsync(input)
+      if (
+        saved.sessionId !== sessionId ||
+        queryClient.getQueryData<WorkspaceSessionSelection>(queryKey)?.selected[destination] !==
+          sessionId
+      )
+        throw new Error('Couldn’t save selected chat')
+    },
+    [queryClient, queryKey, saveSelectedSessionAsync, scope, workspaceId]
+  )
+
   useWorkspaceEvent(event => {
     if (event.type !== 'selected-session:updated' || event.workspaceId !== workspaceId) return
     applySelectedSessionEvent(queryClient, workspaceId, scope === 'shared' && pendingSaves > 0)
@@ -266,19 +295,12 @@ export function useSelectedSession(explicitTabId?: WorkspaceTabId): SelectedSess
           tabId,
           scope === 'browser-tab' ? query.data : undefined
         )
-  return [selectedSessionId, setSelectedSessionId]
+  return [selectedSessionId, setSelectedSessionId, selectSessionForTab]
 }
 
 function useWorkspaceSessionSelection() {
   const workspaceId = useWorkspaceId()
-  return useQuery<WorkspaceSessionSelection>({
-    queryKey: appUiKeys.sessionSelection(workspaceId),
-    queryFn: () => requestJson(`/api/workspaces/${workspaceId}/selected-session`),
-    staleTime: Infinity,
-    gcTime: 0,
-    refetchOnMount: false,
-    refetchOnWindowFocus: false
-  })
+  return useQuery(selectedSessionOptions(workspaceId))
 }
 
 export function usePinnedSession() {
@@ -322,6 +344,7 @@ export function usePinnedSession() {
   return {
     pinnedSessionId: data?.pinned ?? null,
     loaded: data !== undefined,
-    pin: mutation.mutate
+    pin: mutation.mutate,
+    pinAsync: mutation.mutateAsync
   }
 }
diff --git a/client/features/workspace/WorkspaceScreen.tsx b/client/features/workspace/WorkspaceScreen.tsx
index bf328bf4..c8621820 100644
--- a/client/features/workspace/WorkspaceScreen.tsx
+++ b/client/features/workspace/WorkspaceScreen.tsx
@@ -157,6 +157,10 @@ export function WorkspaceScreen({ widgets, views: allViews }: WorkspaceScreenPro
   // Split needs enough row width; the saved mode remains the user's intent.
   const wantsSplit = layout.layoutMode === 'split'
   const mode: LayoutMode = wantsSplit && canUseSplit ? 'split' : 'fullscreen'
+  const revealLinkedChat = useCallback(() => {
+    setFloatingChatOpen(true)
+    setChatFocusRequest(request => request + 1)
+  }, [])
 
   // The tab address: URL in, active tab + applet params out, plus the persisted
   // tab state it keeps in sync. See useWorkspaceNavigation for the invariants.
@@ -169,7 +173,8 @@ export function WorkspaceScreen({ widgets, views: allViews }: WorkspaceScreenPro
     isUnavailable,
     onNavigationClick
   } = useWorkspaceNavigation({
-    views: allViews
+    views: allViews,
+    onOpenChat: revealLinkedChat
   })
 
   // Chat comes after navigation, and takes the address: every message carries
diff --git a/client/features/workspace/useWorkspaceNavigation.test.tsx b/client/features/workspace/useWorkspaceNavigation.test.tsx
index b166ed19..c7d39173 100644
--- a/client/features/workspace/useWorkspaceNavigation.test.tsx
+++ b/client/features/workspace/useWorkspaceNavigation.test.tsx
@@ -1,10 +1,15 @@
-import { expect, spyOn, test } from 'bun:test'
+import { afterEach, beforeEach, describe, expect, spyOn, test } from 'bun:test'
 import { renderToStaticMarkup } from 'react-dom/server'
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
 import { Route, Router } from 'wouter'
 
 import { workspaceKeys } from '@/client/api/workspace-keys'
-import type { ViewInfo } from '@/lib/types'
+import { Workspace } from './WorkspaceContext'
+import { CollabContext } from '@/client/features/collab/provider'
+import { NO_ENGINE } from '@/client/features/collab/client'
+import { createFakeEngine } from '@/client/features/collab/testing/fake-engine'
+import { selectedSessionKey } from '@/client/features/chat/sessions/useSelectedSession'
+import type { SessionInfo, ViewInfo, WorkspaceSessionSelection, WorkspaceTabId } from '@/lib/types'
 import { createDefaultWorkspaceLayout } from '@/lib/workspace-layout'
 import * as workspaceEvents from '@/client/runtime/useWorkspaceEvents'
 import { WorkspaceLayoutContext } from './WorkspaceLayoutContext'
@@ -16,7 +21,9 @@ function readNavigation(
   views: ViewInfo[],
   base = '',
   navigate?: (path: string) => void,
-  queryClient = new QueryClient()
+  queryClient = new QueryClient(),
+  onOpenChat: (tab: WorkspaceTabId) => void = () => {},
+  collab = false
 ) {
   const queryKey = workspaceKeys.views('abc')
   if (!queryClient.getQueryDefaults(queryKey).queryFn)
@@ -25,7 +32,8 @@ function readNavigation(
   const prefix = base === '/' ? '' : base
   function Probe() {
     const { activeTab, appletParams, isUnavailable } = useWorkspaceNavigation({
-      views
+      views,
+      onOpenChat
     })
     return (
       <script type="application/json">
@@ -34,30 +42,43 @@ function readNavigation(
     )
   }
   const html = renderToStaticMarkup(
-    <QueryClientProvider client={queryClient}>
-      <Router
-        base={base}
-        ssrPath={`${prefix}/workspace/abc/${path}`}
-        ssrSearch={search}
-        hook={navigate ? () => [`${prefix}/workspace/abc/${path}`, navigate] : undefined}
+    <Workspace id="abc">
+      <CollabContext
+        value={
+          collab
+            ? createFakeEngine({
+                self: { id: 'self', name: 'Self', color: 'blue' },
+                page: 'overview'
+              })
+            : NO_ENGINE
+        }
       >
-        <Route path="/workspace/:id/*?">
-          <WorkspaceLayoutContext
-            value={{
-              layout: createDefaultWorkspaceLayout(),
-              setLayout: () => {},
-              name: null,
-              cwd: null,
-              provider: null,
-              workspaceId: 'abc',
-              isLoading: false
-            }}
+        <QueryClientProvider client={queryClient}>
+          <Router
+            base={base}
+            ssrPath={`${prefix}/workspace/abc/${path}`}
+            ssrSearch={search}
+            hook={navigate ? () => [`${prefix}/workspace/abc/${path}`, navigate] : undefined}
           >
-            <Probe />
-          </WorkspaceLayoutContext>
-        </Route>
-      </Router>
-    </QueryClientProvider>
+            <Route path="/workspace/:id/*?">
+              <WorkspaceLayoutContext
+                value={{
+                  layout: createDefaultWorkspaceLayout(),
+                  setLayout: () => {},
+                  name: null,
+                  cwd: null,
+                  provider: null,
+                  workspaceId: 'abc',
+                  isLoading: false
+                }}
+              >
+                <Probe />
+              </WorkspaceLayoutContext>
+            </Route>
+          </Router>
+        </QueryClientProvider>
+      </CollabContext>
+    </Workspace>
   )
   if (!html) throw new Error('The workspace route did not match')
   return JSON.parse(html.slice(html.indexOf('>') + 1, html.lastIndexOf('<'))) as Pick<
@@ -87,6 +108,11 @@ test('missing views keep their destination without becoming the default tab', ()
   expect(result.appletParams).toEqual({ eventId: '123' })
 })
 
+test('chat entry routes never render the unavailable page or become tabs', () => {
+  expect(readNavigation('chats/%61bc', '', []).isUnavailable).toBe(false)
+  expect(readNavigation('chats/missing', '', []).activeTab).toBe('overview')
+})
+
 test('legacy browser paths select the same view under a deployment base', () => {
   const views: ViewInfo[] = [{ id: 'events', status: 'compiled', title: 'events' }]
   const result = readNavigation('view:%65vents', 'eventId=123', views, '/prefix')
@@ -175,3 +201,275 @@ test.each(['', '/', '/prefix'])(
     }
   }
 )
+
+function createChatNavigationFixture(collab: boolean) {
+  const views: ViewInfo[] = [
+    { id: 'orders', status: 'compiled', title: 'Orders' },
+    { id: 'draft', status: 'draft', requirements: '' }
+  ]
+  const sessions: SessionInfo[] = [
+    { sessionId: 'general', summary: 'General', lastModified: 1 },
+    { sessionId: 'notes', summary: 'Notes', lastModified: 1, tabId: 'scratchpad' },
+    { sessionId: 'orders', summary: 'Orders', lastModified: 1, tabId: 'views/orders' },
+    { sessionId: 'draft', summary: 'Draft', lastModified: 1, tabId: 'views/draft' },
+    { sessionId: 'gone', summary: 'Gone', lastModified: 1, tabId: 'views/gone' }
+  ]
+  const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } })
+  queryClient.setQueryData(workspaceKeys.sessions('abc'), sessions)
+  const routed: { path: string; replace?: boolean }[] = []
+  const revealed: WorkspaceTabId[] = []
+  const writes: { url: string; body: { sessionId: string | null; tabId?: WorkspaceTabId } }[] = []
+  const selection: WorkspaceSessionSelection = {
+    selected: { overview: 'previous' },
+    pinned: null
+  }
+  queryClient.setQueryData(selectedSessionKey('abc'), selection)
+  const responses: {
+    sessions: Promise<SessionInfo[]>
+    selection: Promise<WorkspaceSessionSelection>
+    pin?: Response
+    save?: Promise<Response>
+    onSave?: () => void
+  } = { sessions: Promise.resolve(sessions), selection: Promise.resolve(selection) }
+  let navigate: (href: string) => void | Promise<void> = () => {}
+  const savedWindow = Object.getOwnPropertyDescriptor(globalThis, 'window')
+  const savedStorage = Object.getOwnPropertyDescriptor(globalThis, 'sessionStorage')
+  const storage = new Map<string, string>()
+  Object.defineProperty(globalThis, 'window', {
+    configurable: true,
+    value: {
+      location: {
+        href: 'http://localhost/prefix/workspace/abc/views/source',
+        pathname: '/prefix/workspace/abc/views/source',
+        search: '',
+        hash: ''
+      }
+    }
+  })
+  Object.defineProperty(globalThis, 'sessionStorage', {
+    configurable: true,
+    value: {
+      getItem: (key: string) => storage.get(key) ?? null,
+      setItem: (key: string, value: string) => storage.set(key, value)
+    }
+  })
+  const fetchSpy = spyOn(globalThis, 'fetch').mockImplementation(
+    Object.assign(
+      async (input: RequestInfo | URL, init?: RequestInit) => {
+        const url = String(input)
+        if (url === '/api/workspaces/abc/sessions') return Response.json(await responses.sessions)
+        if (url.endsWith('/selected-session') && !init?.method)
+          return Response.json(await responses.selection)
+        if (init?.method !== 'PUT') throw new Error(`Unexpected request: ${url}`)
+        const body = JSON.parse(String(init.body)) as {
+          sessionId: string | null
+          tabId?: WorkspaceTabId
+        }
+        writes.push({ url, body })
+        if (url.endsWith('/pinned-session') && responses.pin) return responses.pin
+        if (url.endsWith('/selected-session') && responses.save) {
+          responses.onSave?.()
+          return responses.save
+        }
+        return Response.json(
+          url.endsWith('/pinned-session')
+            ? { pinnedSessionId: body.sessionId }
+            : { sessionId: body.sessionId }
+        )
+      },
+      { preconnect: fetch.preconnect }
+    )
+  )
+  const registration = spyOn(workspaceEvents, 'useNavigationClient').mockImplementation(
+    (_id, callback) => {
+      navigate = callback
+    }
+  )
+  readNavigation(
+    'overview',
+    '',
+    views,
+    '/prefix',
+    (path, options?: { replace?: boolean }) => routed.push({ path, ...options }),
+    queryClient,
+    tab => revealed.push(tab),
+    collab
+  )
+  return {
+    queryClient,
+    sessions,
+    selection,
+    responses,
+    routed,
+    revealed,
+    writes,
+    storage,
+    navigate: (href: string) => Promise.resolve(navigate(href)),
+    cleanup() {
+      fetchSpy.mockRestore()
+      registration.mockRestore()
+      queryClient.clear()
+      if (savedWindow) Object.defineProperty(globalThis, 'window', savedWindow)
+      else Reflect.deleteProperty(globalThis, 'window')
+      if (savedStorage) Object.defineProperty(globalThis, 'sessionStorage', savedStorage)
+      else Reflect.deleteProperty(globalThis, 'sessionStorage')
+    }
+  }
+}
+
+for (const collab of [false, true]) {
+  describe(`chat links with Collab ${collab ? 'enabled' : 'disabled'}`, () => {
+    let fixture: ReturnType<typeof createChatNavigationFixture>
+    beforeEach(() => {
+      fixture = createChatNavigationFixture(collab)
+    })
+    afterEach(() => fixture.cleanup())
+
+    test.each([
+      ['Overview', 'general', 'overview', null],
+      ['Scratchpad', 'notes', 'scratchpad', null],
+      ['a closed compiled view and unpins another chat', 'orders', 'views/orders', 'other'],
+      ['a pending view and preserves the requested pin', 'draft', 'views/draft', 'draft']
+    ] as const)('opens %s', async (_name, id, tab, pinned) => {
+      const { queryClient, selection, navigate, routed, revealed, writes, storage } = fixture
+      queryClient.setQueryData(selectedSessionKey('abc'), { ...selection, pinned })
+      await navigate(`moi:/chats/${id}`)
+      expect(routed).toEqual([{ path: `/prefix/workspace/abc/${tab}`, replace: true }])
+      expect(revealed).toEqual([tab])
+      expect(
+        queryClient.getQueryData<WorkspaceSessionSelection>(selectedSessionKey('abc'))?.pinned
+      ).toBe(pinned === id ? id : null)
+      if (pinned === id) {
+        expect(writes).toEqual([])
+        return
+      }
+      const scope = collab ? 'browser-tab' : 'shared'
+      expect(
+        queryClient.getQueryData<WorkspaceSessionSelection>(selectedSessionKey('abc', scope))
+          ?.selected[tab]
+      ).toBe(id)
+      expect(writes.map(write => write.url)).toEqual([
+        ...(pinned ? ['/api/workspaces/abc/pinned-session'] : []),
+        ...(collab ? [] : ['/api/workspaces/abc/selected-session'])
+      ])
+      if (collab) expect(JSON.parse(storage.get('moi:collab:abc:session')!).selected[tab]).toBe(id)
+    })
+
+    test('waits for pin state on a direct load before selecting', async () => {
+      const { queryClient, responses, selection, navigate, writes, routed, revealed } = fixture
+      queryClient.removeQueries({ queryKey: selectedSessionKey('abc'), exact: true })
+      const loading = Promise.withResolvers<WorkspaceSessionSelection>()
+      responses.selection = loading.promise
+      const opening = navigate('moi:/chats/general')
+      expect(writes).toEqual([])
+      expect(routed).toEqual([])
+      loading.resolve({ ...selection, pinned: 'other' })
+      await opening
+      expect(writes.map(write => write.url)).toEqual([
+        '/api/workspaces/abc/pinned-session',
+        ...(collab ? [] : ['/api/workspaces/abc/selected-session'])
+      ])
+      expect(revealed).toEqual(['overview'])
+    })
+
+    test('opens chats with persisted Agent tab attribution on Overview', async () => {
+      const { queryClient, sessions, navigate, routed, revealed } = fixture
+      queryClient.setQueryData(workspaceKeys.sessions('abc'), [
+        ...sessions,
+        { sessionId: 'legacy', summary: 'Legacy', lastModified: 1, tabId: 'agent' }
+      ])
+      await navigate('moi:/chats/legacy')
+      expect(routed).toEqual([{ path: '/prefix/workspace/abc/overview', replace: true }])
+      expect(revealed).toEqual(['overview'])
+      expect(
+        queryClient.getQueryData<WorkspaceSessionSelection>(
+          selectedSessionKey('abc', collab ? 'browser-tab' : 'shared')
+        )?.selected.overview
+      ).toBe('legacy')
+    })
+
+    test('failed unpinning stops before selection or redirect', async () => {
+      const { queryClient, responses, selection, navigate, writes, routed, revealed } = fixture
+      queryClient.setQueryData(selectedSessionKey('abc'), { ...selection, pinned: 'other' })
+      responses.pin = Response.json({ error: 'Unpin failed' }, { status: 500 })
+      await expect(navigate('moi:/chats/general')).rejects.toThrow()
+      expect(routed).toEqual([])
+      expect(revealed).toEqual([])
+      expect(writes.map(write => write.url)).toEqual(['/api/workspaces/abc/pinned-session'])
+      expect(
+        queryClient.getQueryData<WorkspaceSessionSelection>(selectedSessionKey('abc'))?.pinned
+      ).toBe('other')
+    })
+
+    if (!collab) {
+      test('waits for selection persistence before redirecting or acknowledging', async () => {
+        const { responses, navigate, routed, revealed } = fixture
+        const saving = Promise.withResolvers<Response>()
+        const requested = Promise.withResolvers<void>()
+        responses.save = saving.promise
+        responses.onSave = () => requested.resolve()
+        const opening = navigate('moi:/chats/general')
+        await requested.promise
+        expect(routed).toEqual([])
+        expect(revealed).toEqual([])
+        saving.resolve(Response.json({ sessionId: 'general' }))
+        await opening
+        expect(routed).toEqual([{ path: '/prefix/workspace/abc/overview', replace: true }])
+        expect(revealed).toEqual(['overview'])
+      })
+
+      test('a refused conditional selection save does not open the chat', async () => {
+        const { responses, navigate, routed, revealed } = fixture
+        responses.save = Promise.resolve(Response.json({ sessionId: 'someone-else' }))
+        await expect(navigate('moi:/chats/general')).rejects.toThrow('Couldn’t save selected chat')
+        expect(routed).toEqual([])
+        expect(revealed).toEqual([])
+      })
+    }
+
+    test.each(['missing', 'gone'])(
+      'falls back for %s without changing selection or pin',
+      async id => {
+        const { queryClient, selection, navigate, writes, routed, revealed } = fixture
+        const original = { ...selection, pinned: 'pin' }
+        queryClient.setQueryData(selectedSessionKey('abc'), original)
+        await navigate(`moi:/chats/${id}`)
+        expect(routed).toEqual([{ path: '/prefix/workspace/abc/overview', replace: true }])
+        expect(
+          queryClient.getQueryData<WorkspaceSessionSelection>(selectedSessionKey('abc'))
+        ).toEqual(original)
+        expect(writes).toEqual([])
+        expect(revealed).toEqual([])
+      }
+    )
+
+    test('navigation away cancels a pending lookup without changing selection or pin', async () => {
+      const { queryClient, responses, sessions, selection, navigate, writes, routed, revealed } =
+        fixture
+      const original = { ...selection, pinned: 'pin' }
+      queryClient.setQueryData(selectedSessionKey('abc'), original)
+      const refresh = Promise.withResolvers<SessionInfo[]>()
+      responses.sessions = refresh.promise
+      const opening = navigate('moi:/chats/new')
+      await navigate('moi:/scratchpad')
+      refresh.resolve([...sessions, { sessionId: 'new', summary: 'New', lastModified: 2 }])
+      await expect(opening).rejects.toMatchObject({ name: 'AbortError' })
+      expect(
+        queryClient.getQueryData<WorkspaceSessionSelection>(selectedSessionKey('abc'))
+      ).toEqual(original)
+      expect(writes).toEqual([])
+      expect(revealed).toEqual([])
+      expect(routed.at(-1)?.path).toBe('/prefix/workspace/abc/scratchpad')
+    })
+
+    test('refreshes a missing cached chat before falling back', async () => {
+      const { responses, sessions, navigate, revealed } = fixture
+      responses.sessions = Promise.resolve([
+        ...sessions,
+        { sessionId: 'new', summary: 'New', lastModified: 2 }
+      ])
+      await navigate('moi:/chats/new')
+      expect(revealed).toEqual(['overview'])
+    })
+  })
+}
diff --git a/client/features/workspace/useWorkspaceNavigation.ts b/client/features/workspace/useWorkspaceNavigation.ts
index 13c64cbb..082783ab 100644
--- a/client/features/workspace/useWorkspaceNavigation.ts
+++ b/client/features/workspace/useWorkspaceNavigation.ts
@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useMemo } from 'react'
+import { useCallback, useEffect, useMemo, useRef } from 'react'
 import type { MouseEvent } from 'react'
 import { useQueryClient } from '@tanstack/react-query'
 import { useLocation, useRouter } from 'wouter'
@@ -14,10 +14,19 @@ import { normalizeTabsState, resolveActiveTab, tabAvailable } from './tab-resolu
 import { useWorkspaceLayoutCtx } from './WorkspaceLayoutContext'
 import { useLatestRef } from '@/client/lib/use-latest-ref'
 import { useNavigationClient } from '@/client/runtime/useWorkspaceEvents'
+import {
+  usePinnedSession,
+  useSelectedSession,
+  selectedSessionKey,
+  selectedSessionOptions
+} from '@/client/features/chat/sessions/useSelectedSession'
+import { resolveChatLink } from '@/client/features/chat/sessions/chat-link'
+import type { WorkspaceSessionSelection } from '@/lib/types'
 import type { ViewInfo, WorkspaceTabId, WorkspaceTabsState } from '@/lib/types'
 import {
   addressPath,
   canonicalSearch,
+  chatSessionIdFromPath,
   legacyTabFromPath,
   parseMoiHref,
   readViewParams,
@@ -31,12 +40,20 @@ type NavigationOptions = { replace?: boolean }
 // Memory-only, and scoped by workspace so switching workspaces cannot leak params.
 const rememberedAddresses = new Map<string, Map<WorkspaceTabId, string>>()
 
-type UseWorkspaceNavigationOptions = { views: ViewInfo[] }
+type UseWorkspaceNavigationOptions = {
+  views: ViewInfo[]
+  onOpenChat: (tab: WorkspaceTabId) => void
+}
 
-export function useWorkspaceNavigation({ views }: UseWorkspaceNavigationOptions) {
+export function useWorkspaceNavigation({ views, onOpenChat }: UseWorkspaceNavigationOptions) {
   const queryClient = useQueryClient()
   const { layout, setLayout, workspaceId } = useWorkspaceLayoutCtx()
   const collabEnabled = useCollabEnabled()
+  const [, , selectSessionForTab] = useSelectedSession()
+  const { pinAsync } = usePinnedSession()
+  const chatRequest = useRef<AbortController | null>(null)
+  const workspaceIdRef = useLatestRef(workspaceId)
+  const onOpenChatRef = useLatestRef(onOpenChat)
   const [, navigate] = useLocation()
   const router = useRouter()
   const { base } = router
@@ -58,10 +75,15 @@ export function useWorkspaceNavigation({ views }: UseWorkspaceNavigationOptions)
     return entries
   }, [workspaceId])
   const requestedTab = tabFromPath(path)
+  const isChatLink = path === 'chats' || path.startsWith('chats/')
+  const linkedSessionId = chatSessionIdFromPath(path)
   const legacyTab = requestedTab ? null : legacyTabFromPath(path)
   const activeTab = resolveActiveTab(requestedTab ?? legacyTab, tabsState, views)
   const isUnavailable =
-    Boolean(path) && !legacyTab && (!requestedTab || !tabAvailable(requestedTab, views))
+    Boolean(path) &&
+    !isChatLink &&
+    !legacyTab &&
+    (!requestedTab || !tabAvailable(requestedTab, views))
   const honored = requestedTab === activeTab && !isUnavailable
 
   const setTabs = useCallback(
@@ -75,6 +97,7 @@ export function useWorkspaceNavigation({ views }: UseWorkspaceNavigationOptions)
 
   const go = useCallback(
     (target: string, options: NavigationOptions = {}) => {
+      chatRequest.current?.abort()
       const current = window.location.pathname + canonicalSearch(window.location.search)
       const absolute = `${base}${target}`
       if (current !== absolute || window.location.hash) navigate(target, options)
@@ -89,8 +112,57 @@ export function useWorkspaceNavigation({ views }: UseWorkspaceNavigationOptions)
     [go, remembered, workspaceId]
   )
 
+  const openLinkedChat = useLatestRef(
+    async (sessionId: string, controller = new AbortController()) => {
+      chatRequest.current?.abort()
+      chatRequest.current = controller
+      const originalUrl = window.location.href
+      const checkCurrent = () => {
+        if (window.location.href !== originalUrl || workspaceIdRef.current !== workspaceId)
+          controller.abort()
+        controller.signal.throwIfAborted()
+      }
+      try {
+        const tab = await resolveChatLink(
+          queryClient,
+          workspaceId,
+          sessionId,
+          views,
+          controller.signal
+        )
+        checkCurrent()
+        if (!tab) {
+          go(addressPath(workspaceId, { tab: 'overview', search: '' }), { replace: true })
+          return
+        }
+        // Direct loads can resolve the chat before selection and pin state load.
+        await queryClient.ensureQueryData(selectedSessionOptions(workspaceId))
+        if (collabEnabled)
+          await queryClient.ensureQueryData(selectedSessionOptions(workspaceId, 'browser-tab'))
+        checkCurrent()
+        const pinned = queryClient.getQueryData<WorkspaceSessionSelection>(
+          selectedSessionKey(workspaceId)
+        )?.pinned
+        if (pinned && pinned !== sessionId) {
+          await pinAsync(null)
+          checkCurrent()
+        }
+        if (pinned !== sessionId) {
+          await selectSessionForTab(sessionId, tab)
+          checkCurrent()
+        }
+        go(addressPath(workspaceId, { tab, search: '' }), { replace: true })
+        onOpenChatRef.current(tab)
+      } finally {
+        if (chatRequest.current === controller) chatRequest.current = null
+      }
+    }
+  )
+
+  useEffect(() => () => chatRequest.current?.abort(), [path, search, workspaceId])
+
   const navigateHref = useCallback(
-    (href: string, availableViews = views) => {
+    async (href: string, availableViews = views) => {
       const target = resolveUrl(href, {
         apiBase: `/api/workspaces/${encodeURIComponent(workspaceId)}`,
         workspacePath: workspacePath(workspaceId)
@@ -100,15 +172,20 @@ export function useWorkspaceNavigation({ views }: UseWorkspaceNavigationOptions)
         return
       }
       const address = parseMoiHref(href)
+      if ('sessionId' in address) {
+        await openLinkedChat.current(address.sessionId)
+        return
+      }
       if (!tabAvailable(address.tab, availableViews))
         throw new Error('This destination is unavailable in this workspace')
       go(target)
     },
-    [go, views, workspaceId]
+    [go, openLinkedChat, views, workspaceId]
   )
 
   const reportError = useCallback(
     (error: unknown) => {
+      if (error instanceof Error && error.name === 'AbortError') return
       const message = error instanceof Error ? error.message : 'Navigation failed'
       toast.add({ type: 'error', title: 'Could not navigate', description: message })
       reportAppletError(workspaceId, { source: 'runtime', message })
@@ -117,21 +194,33 @@ export function useWorkspaceNavigation({ views }: UseWorkspaceNavigationOptions)
   )
 
   useAppletEvent(workspaceId, 'navigate', href => {
-    try {
-      navigateHref(href)
-    } catch (error) {
-      reportError(error)
-    }
+    void navigateHref(href).catch(reportError)
   })
   useNavigationClient(workspaceId, async href => {
     const queryKey = workspaceKeys.views(workspaceId)
-    if (href.startsWith('moi:/views/') && !tabAvailable(parseMoiHref(href).tab, views))
-      await queryClient.refetchQueries({ queryKey, exact: true }, { throwOnError: true })
-    navigateHref(href, queryClient.getQueryData<ViewInfo[]>(queryKey) ?? views)
+    if (href.startsWith('moi:/views/')) {
+      const address = parseMoiHref(href)
+      if ('tab' in address && !tabAvailable(address.tab, views))
+        await queryClient.refetchQueries({ queryKey, exact: true }, { throwOnError: true })
+    }
+    await navigateHref(href, queryClient.getQueryData<ViewInfo[]>(queryKey) ?? views)
   })
 
-  // Bare workspace URLs and old view bookmarks are
-  // the only redirects. Missing destinations keep their URL and show recovery.
+  useEffect(() => {
+    if (!isChatLink) return
+    if (!linkedSessionId) {
+      go(addressPath(workspaceId, { tab: 'overview', search: '' }), { replace: true })
+      return
+    }
+    const controller = new AbortController()
+    void openLinkedChat.current(linkedSessionId, controller).catch(error => {
+      if (!controller.signal.aborted) reportError(error)
+    })
+    return () => controller.abort()
+  }, [go, isChatLink, linkedSessionId, openLinkedChat, path, reportError, search, workspaceId])
+
+  // Bare workspace URLs and old view bookmarks
+  // redirect separately from exact chat links. Missing views show recovery.
   useEffect(() => {
     if (isUnavailable) return
     if (legacyTab) {
@@ -175,12 +264,19 @@ export function useWorkspaceNavigation({ views }: UseWorkspaceNavigationOptions)
       // In-page fragments continue using native browser behavior.
       if (url.hash) return
       const tab = tabFromPath(url.pathname.slice(prefix.length))
-      if (!tab) return
+      const sessionId = chatSessionIdFromPath(url.pathname.slice(prefix.length))
+      if (!tab && !sessionId) return
       event.preventDefault()
+      if (sessionId) {
+        // Entering the route gives in-app links normal Back behavior; the
+        // resolver then replaces this intermediate address with the home tab.
+        go(url.pathname.slice(base.length) + url.search)
+        return
+      }
       try {
-        if (!tabAvailable(tab, views))
+        if (!tabAvailable(tab!, views))
           throw new Error('This destination is unavailable in this workspace')
-        go(addressPath(workspaceId, { tab, search: canonicalSearch(url.search) }))
+        go(addressPath(workspaceId, { tab: tab!, search: canonicalSearch(url.search) }))
       } catch (error) {
         reportError(error)
       }
diff --git a/docs/navigation.md b/docs/navigation.md
index 5265edd8..603073f2 100644
--- a/docs/navigation.md
+++ b/docs/navigation.md
@@ -5,6 +5,7 @@ Portable addresses identify destinations inside the current workspace:
 - `moi:/overview`
 - `moi:/scratchpad`
 - `moi:/views/events?eventId=123`
+- `moi:/chats/<session-id>`
 - `moi:/files/clips/video.mp4`
 
 The host resolves these to `/workspace/<id>/views/events?eventId=123`. Domain and deployment
@@ -33,6 +34,24 @@ last addresses in browser memory. A tab click restores its address; an explicit
 exact state to open. Only the active URL survives reload. Parked views retain their own params.
 Layout persistence still stores tab order and the default tab, without query strings.
 
+## Exact chat links
+
+`moi:/chats/<session-id>` resolves inside the current workspace and opens the chat's
+home tab, selects the chat, and reveals the sidebar or popup. Its browser address is
+`/workspace/<workspace-id>/chats/<session-id>`. Chats without tab
+attribution, including old Agent chats, open on Overview. Both pending and compiled
+views are valid destinations. The entry route is replaced with the tab's plain URL;
+it creates no separate chat tab and forwards no view parameters.
+
+Opening a different chat unpins the workspace's current chat before selecting the
+requested one. Linking to the already pinned chat preserves its pin. Selection uses
+the existing persistence: browser-tab-local with Collab enabled, shared otherwise.
+Missing chats or missing home tabs quietly redirect to Overview without changing
+selection or the workspace pin. Navigation away cancels pending link resolution.
+
+Copying the resulting address bar URL links to the tab. Exact chat links keep the
+`moi:/chats/<session-id>` form; browser history does not track per-tab chat selections.
+
 Invalid action requests do not navigate. An unavailable direct browser address stays in the URL
 and shows recovery to Overview.
 
@@ -45,7 +64,9 @@ showing that workspace, even after focus moves to a terminal. A sole client need
 multiple clients without a focus record require the user to focus one first.
 
 The browser checks that the destination exists and acknowledges after applying the URL, without
-waiting for view data. Only the addressed socket may settle its request.
+waiting for view data. Chat links also await resolution, unpinning when needed, and
+selection persistence before acknowledging, without waiting for the transcript.
+Only the addressed socket may settle its request.
 Disconnects and workspace switches fail pending requests. The
 five-second timeout does not retry: navigation may already have happened.
 
diff --git a/lib/navigation.test.ts b/lib/navigation.test.ts
index 06b3f797..7483fdce 100644
--- a/lib/navigation.test.ts
+++ b/lib/navigation.test.ts
@@ -2,8 +2,9 @@ import { describe, expect, test } from 'bun:test'
 import {
   addressPath,
   canonicalSearch,
+  chatSessionIdFromPath,
+  destinationHref,
   legacyTabFromPath,
-  moiHref,
   parseMoiHref,
   readViewParams,
   resolveUrl,
@@ -15,7 +16,10 @@ const context = { apiBase: '/api/workspaces/abc', workspacePath: '/workspace/abc
 
 describe('workspace addresses', () => {
   test('tab IDs are the workspace-relative paths', () => {
-    expect(parseMoiHref('moi:/views/events?eventId=123').tab).toBe('views/events')
+    expect(parseMoiHref('moi:/views/events?eventId=123')).toEqual({
+      tab: 'views/events',
+      search: '?eventId=123'
+    })
     expect(workspaceTabPath('ws1', 'views/events')).toBe('/workspace/ws1/views/events')
   })
 
@@ -32,7 +36,7 @@ describe('workspace addresses', () => {
   test('round trips a destination independently of workspace, origin, and deployment prefix', () => {
     const href = 'moi:/views/events?eventId=123'
     const address = parseMoiHref(href)
-    expect(moiHref(address.tab, address.search)).toBe(href)
+    expect(destinationHref(address)).toBe(href)
     expect(addressPath('abc', address)).toBe('/workspace/abc/views/events?eventId=123')
     expect(addressPath('other', address, '/prefix/')).toBe(
       '/prefix/workspace/other/views/events?eventId=123'
@@ -43,7 +47,10 @@ describe('workspace addresses', () => {
     )
   })
   test('accepts encoded IDs supported by the applet server', () => {
-    expect(parseMoiHref('moi:/views/%65vents_2026-09').tab).toBe('views/events_2026-09')
+    expect(parseMoiHref('moi:/views/%65vents_2026-09')).toEqual({
+      tab: 'views/events_2026-09',
+      search: ''
+    })
   })
 
   test('query values remain strings and follow URLSearchParams.get semantics', () => {
@@ -75,12 +82,27 @@ describe('workspace addresses', () => {
       'moi:/views/../overview',
       'moi:/views/a#part',
       'moi:/view-builders/a',
-      'moi:/chats/a',
+      'moi:/agent',
+      'moi:/chats/',
+      'moi:/chats/a/b',
+      'moi:/chats/%2f',
+      'moi:/chats/%',
       'moi:/files/a.md'
     ]) {
       expect(() => parseMoiHref(href)).toThrow()
     }
   })
+  test('chat entry routes round trip without becoming workspace tabs', () => {
+    const address = parseMoiHref('moi:/chats/%61bc')
+    expect(address).toEqual({ sessionId: 'abc', search: '' })
+    expect(destinationHref(address)).toBe('moi:/chats/abc')
+    expect(addressPath('ws1', address, '/prefix')).toBe('/prefix/workspace/ws1/chats/abc')
+    expect(resolveUrl('moi:/chats/abc', context)).toBe('/workspace/abc/chats/abc')
+    expect(tabFromPath('chats/abc')).toBeNull()
+    expect(chatSessionIdFromPath('chats/provider%3Aid')).toBe('provider:id')
+    expect(chatSessionIdFromPath('chats/%252f')).toBe('%2f')
+    expect(chatSessionIdFromPath('chats/..')).toBeNull()
+  })
   test('current tabs round trip through browser paths', () => {
     for (const tab of ['overview', 'scratchpad', 'views/events'] as const) {
       expect(tabFromPath(tab)).toBe(tab)
diff --git a/lib/navigation.ts b/lib/navigation.ts
index 5ade3226..5099e4b5 100644
--- a/lib/navigation.ts
+++ b/lib/navigation.ts
@@ -3,20 +3,38 @@ import { isWorkspaceTabId } from './workspace-tabs'
 
 export type ViewParams = Record<string, string>
 export type WorkspaceAddress = { tab: WorkspaceTabId; search: string }
+export type WorkspaceDestination = WorkspaceAddress | { sessionId: string; search: string }
 
-export function parseMoiHref(href: unknown): WorkspaceAddress {
+export function parseMoiHref(href: unknown): WorkspaceDestination {
   if (typeof href !== 'string' || !href.startsWith('moi:/') || href.startsWith('moi://')) {
     throw new Error('Expected a workspace address such as moi:/views/events?eventId=123')
   }
   const path = href.slice(5).split(/[?#]/, 1)[0]
   if (href.includes('#') || /[\s\\]/.test(path)) throw new Error('Invalid workspace address')
   const tab = tabFromPath(path)
-  if (!tab) {
+  const sessionId = chatSessionIdFromPath(path)
+  if (!tab && !sessionId) {
     throw new Error(`Unsupported workspace destination: ${path}`)
   }
   const query = href.indexOf('?')
   const search = query < 0 ? '' : canonicalSearch(href.slice(query + 1))
-  return { tab, search }
+  return sessionId ? { sessionId, search } : { tab: tab!, search }
+}
+
+export function chatSessionIdFromPath(path: string): string | null {
+  if (!path.startsWith('chats/')) return null
+  try {
+    const id = decodeURIComponent(path.slice('chats/'.length))
+    return id && id !== '.' && id !== '..' && !/[/\\\s\0]/.test(id) ? id : null
+  } catch {
+    return null
+  }
+}
+
+export function destinationHref(address: WorkspaceDestination): string {
+  return 'sessionId' in address
+    ? `moi:/chats/${encodeURIComponent(address.sessionId)}${address.search}`
+    : moiHref(address.tab, address.search)
 }
 
 export function canonicalSearch(search: string): string {
@@ -57,8 +75,8 @@ export function workspacePath(workspaceId: string, base = ''): string {
   return `${base.replace(/\/$/, '')}/workspace/${encodeURIComponent(workspaceId)}`
 }
 
-export function addressPath(workspaceId: string, address: WorkspaceAddress, base = ''): string {
-  return `${workspacePath(workspaceId, base)}/${address.tab}${address.search}`
+export function addressPath(workspaceId: string, address: WorkspaceDestination, base = ''): string {
+  return `${workspacePath(workspaceId, base)}/${destinationHref(address).slice(5)}`
 }
 
 export function workspaceTabPath(workspaceId: string, tab: WorkspaceTabId): string {
@@ -83,8 +101,10 @@ export function resolveUrl(url: string, context: ResolveUrlContext): string {
     return `${context.apiBase}/files/${segments.join('/')}${suffix}`
   }
   if (url.startsWith('moi:')) {
-    const { tab, search } = parseMoiHref(url)
-    return context.workspacePath ? `${context.workspacePath}/${tab}${search}` : ''
+    const address = parseMoiHref(url)
+    return context.workspacePath
+      ? `${context.workspacePath}/${destinationHref(address).slice(5)}`
+      : ''
   }
   // Only explicit ordinary web addresses may leave the workspace through the
   // imperative API. Native anchors keep their existing protocol policy.
diff --git a/server/control.ts b/server/control.ts
index f4dd828c..c4829ae9 100644
--- a/server/control.ts
+++ b/server/control.ts
@@ -4,7 +4,7 @@ import { resolve } from 'path'
 import { parseAppletSelector } from '@/lib/applet-selector'
 import { resolveWorkspaceTheme } from '@/lib/themes'
 import type { WorkspaceEntry } from '@/lib/types'
-import { moiHref, parseMoiHref } from '@/lib/navigation'
+import { destinationHref, moiHref, parseMoiHref } from '@/lib/navigation'
 import { navigationRelay } from './navigation-relay'
 
 import { clearAppletLog, getAppletLog, getAppletLogCount } from './applet-log'
@@ -322,8 +322,9 @@ export const control = Bun.serve({
           if (!match) return
           try {
             const address = parseMoiHref(data.href)
-            const href = moiHref(address.tab, address.search)
-            assertNavigableTab(address.tab, await getWorkspaceViews(match.path))
+            const href = destinationHref(address)
+            if ('tab' in address)
+              assertNavigableTab(address.tab, await getWorkspaceViews(match.path))
             await navigationRelay.navigate(match.id, href)
             ws.send(JSON.stringify({ ok: true, href }))
           } catch (error) {
diff --git a/server/test/navigation-cli.test.ts b/server/test/navigation-cli.test.ts
index cfa6974a..338ad0b7 100644
--- a/server/test/navigation-cli.test.ts
+++ b/server/test/navigation-cli.test.ts
@@ -3,37 +3,40 @@ import { join } from 'node:path'
 
 const CLI = join(import.meta.dir, '..', 'cli.ts')
 
-test('navigation CLI sends a portable address and waits for a matching response', async () => {
-  let request: unknown
-  const server = Bun.serve({
-    port: 0,
-    hostname: '127.0.0.1',
-    fetch(req, server) {
-      if (server.upgrade(req)) return
-      return new Response('', { status: 400 })
-    },
-    websocket: {
-      message(ws, message) {
-        request = JSON.parse(String(message))
-        ws.send(JSON.stringify({ ok: true, href: 'moi:/overview' }))
+test.each(['moi:/overview', 'moi:/chats/chat-1'])(
+  'navigation CLI sends %s and waits for acknowledgement',
+  async href => {
+    let request: unknown
+    const server = Bun.serve({
+      port: 0,
+      hostname: '127.0.0.1',
+      fetch(req, server) {
+        if (server.upgrade(req)) return
+        return new Response('', { status: 400 })
+      },
+      websocket: {
+        message(ws, message) {
+          request = JSON.parse(String(message))
+          ws.send(JSON.stringify({ ok: true, href }))
+        }
       }
-    }
-  })
-  try {
-    const proc = Bun.spawn(['bun', CLI, 'navigate', 'moi:/overview'], {
-      env: { ...process.env, MOI_CONTROL_PORT: String(server.port) },
-      stdout: 'pipe',
-      stderr: 'pipe'
     })
-    const [output, code] = await Promise.all([new Response(proc.stdout).text(), proc.exited])
-    expect(request).toMatchObject({ type: 'navigate', href: 'moi:/overview' })
-    expect(request).not.toHaveProperty('replace')
-    expect(code).toBe(0)
-    expect(output).toContain('Navigated to moi:/overview')
-  } finally {
-    server.stop(true)
+    try {
+      const proc = Bun.spawn(['bun', CLI, 'navigate', href], {
+        env: { ...process.env, MOI_CONTROL_PORT: String(server.port) },
+        stdout: 'pipe',
+        stderr: 'pipe'
+      })
+      const [output, code] = await Promise.all([new Response(proc.stdout).text(), proc.exited])
+      expect(request).toMatchObject({ type: 'navigate', href })
+      expect(request).not.toHaveProperty('replace')
+      expect(code).toBe(0)
+      expect(output).toContain(`Navigated to ${href}`)
+    } finally {
+      server.stop(true)
+    }
   }
-})
+)
 
 test('navigation CLI exits nonzero when the control server disconnects without acknowledgement', async () => {
   const server = Bun.serve({

From 2846c4febaeb10c3e6e72530514366e4c025fb4b Mon Sep 17 00:00:00 2001
From: Anton Frehser <hey@tonyfresher.com>
Date: Wed, 7 Oct 2026 18:19:56 +0200
Subject: [PATCH 2/3] Simplify chat link navigation and test mounted flows

---
 bun.lock                                      |   1 +
 .../use-workspace-navigation.dom.test.tsx     | 210 ++++++++++++++++++
 .../workspace/useWorkspaceNavigation.test.tsx |  64 +++---
 .../workspace/useWorkspaceNavigation.ts       |  14 +-
 package.json                                  |   1 +
 5 files changed, 254 insertions(+), 36 deletions(-)
 create mode 100644 client/features/workspace/use-workspace-navigation.dom.test.tsx

diff --git a/bun.lock b/bun.lock
index a7ad8cd8..66acfda2 100644
--- a/bun.lock
+++ b/bun.lock
@@ -69,6 +69,7 @@
         "@types/react-resizable": "^3.0.8",
         "date-fns": "^4.4.0",
         "embla-carousel-react": "^8.6.0",
+        "linkedom": "0.18.12",
         "oxfmt": "^0.54.0",
         "oxlint": "^1.82.0",
         "react-day-picker": "^10.0.1",
diff --git a/client/features/workspace/use-workspace-navigation.dom.test.tsx b/client/features/workspace/use-workspace-navigation.dom.test.tsx
new file mode 100644
index 00000000..2cce0c26
--- /dev/null
+++ b/client/features/workspace/use-workspace-navigation.dom.test.tsx
@@ -0,0 +1,210 @@
+import { afterEach, describe, expect, spyOn, test } from 'bun:test'
+import { act, useState } from 'react'
+import { createRoot } from 'react-dom/client'
+import { parseHTML } from 'linkedom'
+import { notifyManager, QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { Link, Route, Router } from 'wouter'
+
+import { workspaceKeys } from '@/client/api/workspace-keys'
+import { selectedSessionKey } from '@/client/features/chat/sessions/useSelectedSession'
+import { CollabContext } from '@/client/features/collab/provider'
+import { NO_ENGINE } from '@/client/features/collab/client'
+import { createFakeEngine } from '@/client/features/collab/testing/fake-engine'
+import * as workspaceEvents from '@/client/runtime/useWorkspaceEvents'
+import { addressPath } from '@/lib/navigation'
+import { createDefaultWorkspaceLayout } from '@/lib/workspace-layout'
+import type { WorkspaceSessionSelection } from '@/lib/types'
+import { Workspace } from './WorkspaceContext'
+import { WorkspaceLayoutContext } from './WorkspaceLayoutContext'
+import { useWorkspaceNavigation } from './useWorkspaceNavigation'
+
+let cleanup: () => Promise<void> = async () => {}
+afterEach(() => cleanup())
+
+function mountNavigation(path: string, collab: boolean) {
+  const { window, document } = parseHTML('<html><body><div id="root"></div></body></html>')
+  const location = new URL(`http://localhost/prefix/workspace/abc/${path}`)
+  Object.defineProperty(window, 'location', { configurable: true, value: location })
+  const storage = new Map<string, string>()
+  const globals = {
+    window,
+    document,
+    location,
+    Element: window.Element,
+    HTMLElement: window.HTMLElement,
+    HTMLAnchorElement: window.HTMLAnchorElement,
+    addEventListener: window.addEventListener.bind(window),
+    removeEventListener: window.removeEventListener.bind(window),
+    history: {
+      pushState: (_state: unknown, _title: string, href: string) => move(href),
+      replaceState: (_state: unknown, _title: string, href: string) => move(href)
+    },
+    sessionStorage: {
+      getItem: (key: string) => storage.get(key) ?? null,
+      setItem: (key: string, value: string) => storage.set(key, value)
+    },
+    IS_REACT_ACT_ENVIRONMENT: true
+  }
+  function move(href: string) {
+    location.href = new URL(href, location).href
+    window.dispatchEvent(new window.Event('popstate'))
+  }
+  const descriptors = new Map(
+    Object.keys(globals).map(key => [key, Object.getOwnPropertyDescriptor(globalThis, key)])
+  )
+  for (const [key, value] of Object.entries(globals))
+    Object.defineProperty(globalThis, key, { configurable: true, value })
+  notifyManager.setNotifyFunction(callback => {
+    act(callback)
+  })
+
+  const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } })
+  let selection: WorkspaceSessionSelection = { selected: { overview: 'previous' }, pinned: 'other' }
+  queryClient.setQueryData(workspaceKeys.sessions('abc'), [
+    { sessionId: 'source', summary: 'Source', lastModified: 1, tabId: 'scratchpad' }
+  ])
+  queryClient.setQueryData(selectedSessionKey('abc'), selection)
+  const fetchSpy = spyOn(globalThis, 'fetch').mockImplementation(
+    Object.assign(
+      async (input: RequestInfo | URL, init?: RequestInit) => {
+        const url = String(input)
+        if (url.endsWith('/selected-session') && !init?.method) return Response.json(selection)
+        const body = JSON.parse(String(init?.body)) as { sessionId: string; tabId: string }
+        if (url.endsWith('/pinned-session')) {
+          selection = { ...selection, pinned: null }
+          return Response.json({ pinnedSessionId: null })
+        }
+        if (url.endsWith('/selected-session')) {
+          selection = {
+            ...selection,
+            selected: { ...selection.selected, [body.tabId]: body.sessionId }
+          }
+          return Response.json({ sessionId: body.sessionId })
+        }
+        throw new Error(`Unexpected request: ${url}`)
+      },
+      { preconnect: fetch.preconnect }
+    )
+  )
+  const navigationSpy = spyOn(workspaceEvents, 'useNavigationClient').mockImplementation(() => {})
+  const eventsSpy = spyOn(workspaceEvents, 'useWorkspaceEvent').mockImplementation(() => {})
+
+  function Probe() {
+    const [revealed, setRevealed] = useState(false)
+    const { activeTab, onNavigationClick } = useWorkspaceNavigation({
+      views: [],
+      onOpenChat: () => setRevealed(true)
+    })
+    return (
+      <div onClick={onNavigationClick}>
+        <Link data-link="source" href={addressPath('abc', { sessionId: 'source', search: '' })}>
+          Started from another chat
+        </Link>
+        <a
+          data-link="native"
+          href={`http://localhost${addressPath('abc', { sessionId: 'source', search: '' }, '/prefix')}`}
+        >
+          Chat link
+        </a>
+        <output id="active-tab">{activeTab}</output>
+        <output id="revealed">{revealed ? 'yes' : 'no'}</output>
+      </div>
+    )
+  }
+  const root = createRoot(document.getElementById('root')!)
+  cleanup = async () => {
+    await act(async () => {
+      root.unmount()
+      queryClient.clear()
+      await Bun.sleep(0)
+    })
+    notifyManager.setNotifyFunction(callback => callback())
+    fetchSpy.mockRestore()
+    navigationSpy.mockRestore()
+    eventsSpy.mockRestore()
+    for (const [key, descriptor] of descriptors) {
+      if (descriptor) Object.defineProperty(globalThis, key, descriptor)
+      else Reflect.deleteProperty(globalThis, key)
+    }
+  }
+  const render = () =>
+    act(async () => {
+      root.render(
+        <Workspace id="abc">
+          <CollabContext
+            value={
+              collab
+                ? createFakeEngine({
+                    self: { id: 'self', name: 'Self', color: 'blue' },
+                    page: 'overview'
+                  })
+                : NO_ENGINE
+            }
+          >
+            <QueryClientProvider client={queryClient}>
+              <Router base="/prefix">
+                <Route path="/workspace/:id/*?">
+                  <WorkspaceLayoutContext
+                    value={{
+                      layout: createDefaultWorkspaceLayout(),
+                      setLayout: () => {},
+                      name: null,
+                      cwd: null,
+                      provider: null,
+                      workspaceId: 'abc',
+                      isLoading: false
+                    }}
+                  >
+                    <Probe />
+                  </WorkspaceLayoutContext>
+                </Route>
+              </Router>
+            </QueryClientProvider>
+          </CollabContext>
+        </Workspace>
+      )
+    })
+  const waitForNavigation = async () => {
+    for (let i = 0; i < 50 && document.getElementById('revealed')?.textContent !== 'yes'; i++)
+      await act(async () => {
+        await Bun.sleep(10)
+      })
+    expect(location.pathname).toBe('/prefix/workspace/abc/scratchpad')
+    expect(document.getElementById('active-tab')?.textContent).toBe('scratchpad')
+    expect(document.getElementById('revealed')?.textContent).toBe('yes')
+    expect(
+      queryClient.getQueryData<WorkspaceSessionSelection>(selectedSessionKey('abc'))?.pinned
+    ).toBeNull()
+    expect(
+      queryClient.getQueryData<WorkspaceSessionSelection>(
+        selectedSessionKey('abc', collab ? 'browser-tab' : 'shared')
+      )?.selected.scratchpad
+    ).toBe('source')
+  }
+  return { render, document, window, waitForNavigation }
+}
+
+for (const collab of [false, true]) {
+  describe(`mounted chat links with Collab ${collab ? 'enabled' : 'disabled'}`, () => {
+    test('a direct chat URL selects and reveals its chat through the route effect', async () => {
+      const fixture = mountNavigation('chats/source', collab)
+      await fixture.render()
+      await fixture.waitForNavigation()
+    })
+
+    test.each(['source', 'native'])(
+      'clicking a %s chat link selects and reveals its chat',
+      async kind => {
+        const fixture = mountNavigation('overview', collab)
+        await fixture.render()
+        const click = new fixture.window.Event('click', { bubbles: true, cancelable: true })
+        Object.assign(click, { button: 0 })
+        await act(async () => {
+          fixture.document.querySelector(`a[data-link="${kind}"]`)!.dispatchEvent(click)
+        })
+        expect(click.defaultPrevented).toBe(true)
+        await fixture.waitForNavigation()
+      }
+    )
+  })
+}
diff --git a/client/features/workspace/useWorkspaceNavigation.test.tsx b/client/features/workspace/useWorkspaceNavigation.test.tsx
index c7d39173..14af239a 100644
--- a/client/features/workspace/useWorkspaceNavigation.test.tsx
+++ b/client/features/workspace/useWorkspaceNavigation.test.tsx
@@ -15,15 +15,25 @@ import * as workspaceEvents from '@/client/runtime/useWorkspaceEvents'
 import { WorkspaceLayoutContext } from './WorkspaceLayoutContext'
 import { useWorkspaceNavigation } from './useWorkspaceNavigation'
 
+type ReadNavigationOptions = {
+  base?: string
+  navigate?: (path: string, options?: { replace?: boolean }) => void
+  queryClient?: QueryClient
+  onOpenChat?: () => void
+  collab?: boolean
+}
+
 function readNavigation(
   path: string,
   search: string,
   views: ViewInfo[],
-  base = '',
-  navigate?: (path: string) => void,
-  queryClient = new QueryClient(),
-  onOpenChat: (tab: WorkspaceTabId) => void = () => {},
-  collab = false
+  {
+    base = '',
+    navigate,
+    queryClient = new QueryClient(),
+    onOpenChat = () => {},
+    collab = false
+  }: ReadNavigationOptions = {}
 ) {
   const queryKey = workspaceKeys.views('abc')
   if (!queryClient.getQueryDefaults(queryKey).queryFn)
@@ -97,8 +107,12 @@ test('view params decode exactly once through the real router', () => {
 
 test('encoded IDs resolve under a deployment base without decoding nested escapes', () => {
   const views: ViewInfo[] = [{ id: 'events', status: 'compiled', title: 'events' }]
-  expect(readNavigation('views/%65vents', '', views, '/prefix').activeTab).toBe('views/events')
-  expect(readNavigation('views/%2565vents', '', views, '/prefix').isUnavailable).toBe(true)
+  expect(readNavigation('views/%65vents', '', views, { base: '/prefix' }).activeTab).toBe(
+    'views/events'
+  )
+  expect(readNavigation('views/%2565vents', '', views, { base: '/prefix' }).isUnavailable).toBe(
+    true
+  )
 })
 
 test('missing views keep their destination without becoming the default tab', () => {
@@ -115,7 +129,7 @@ test('chat entry routes never render the unavailable page or become tabs', () =>
 
 test('legacy browser paths select the same view under a deployment base', () => {
   const views: ViewInfo[] = [{ id: 'events', status: 'compiled', title: 'events' }]
-  const result = readNavigation('view:%65vents', 'eventId=123', views, '/prefix')
+  const result = readNavigation('view:%65vents', 'eventId=123', views, { base: '/prefix' })
   expect(result.activeTab).toBe('views/events')
   expect(result.isUnavailable).toBe(false)
   expect(result.appletParams).toEqual({ eventId: '123' })
@@ -156,16 +170,13 @@ test.each(['', '/', '/prefix'])(
       }
     )
     try {
-      readNavigation(
-        'overview',
-        '',
-        views,
+      readNavigation('overview', '', views, {
         base,
-        path => {
+        navigate: path => {
           routedPaths.push(path)
         },
         queryClient
-      )
+      })
       await navigate('moi:/views/orders?order=o-1')
       await navigate('moi:/files/clips/a%20b.mp4?version=2#t=5')
       await navigate('https://example.com/')
@@ -217,7 +228,7 @@ function createChatNavigationFixture(collab: boolean) {
   const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } })
   queryClient.setQueryData(workspaceKeys.sessions('abc'), sessions)
   const routed: { path: string; replace?: boolean }[] = []
-  const revealed: WorkspaceTabId[] = []
+  const revealed: boolean[] = []
   const writes: { url: string; body: { sessionId: string | null; tabId?: WorkspaceTabId } }[] = []
   const selection: WorkspaceSessionSelection = {
     selected: { overview: 'previous' },
@@ -285,16 +296,13 @@ function createChatNavigationFixture(collab: boolean) {
       navigate = callback
     }
   )
-  readNavigation(
-    'overview',
-    '',
-    views,
-    '/prefix',
-    (path, options?: { replace?: boolean }) => routed.push({ path, ...options }),
+  readNavigation('overview', '', views, {
+    base: '/prefix',
+    navigate: (path, options) => routed.push({ path, ...options }),
     queryClient,
-    tab => revealed.push(tab),
+    onOpenChat: () => revealed.push(true),
     collab
-  )
+  })
   return {
     queryClient,
     sessions,
@@ -335,7 +343,7 @@ for (const collab of [false, true]) {
       queryClient.setQueryData(selectedSessionKey('abc'), { ...selection, pinned })
       await navigate(`moi:/chats/${id}`)
       expect(routed).toEqual([{ path: `/prefix/workspace/abc/${tab}`, replace: true }])
-      expect(revealed).toEqual([tab])
+      expect(revealed).toEqual([true])
       expect(
         queryClient.getQueryData<WorkspaceSessionSelection>(selectedSessionKey('abc'))?.pinned
       ).toBe(pinned === id ? id : null)
@@ -369,7 +377,7 @@ for (const collab of [false, true]) {
         '/api/workspaces/abc/pinned-session',
         ...(collab ? [] : ['/api/workspaces/abc/selected-session'])
       ])
-      expect(revealed).toEqual(['overview'])
+      expect(revealed).toEqual([true])
     })
 
     test('opens chats with persisted Agent tab attribution on Overview', async () => {
@@ -380,7 +388,7 @@ for (const collab of [false, true]) {
       ])
       await navigate('moi:/chats/legacy')
       expect(routed).toEqual([{ path: '/prefix/workspace/abc/overview', replace: true }])
-      expect(revealed).toEqual(['overview'])
+      expect(revealed).toEqual([true])
       expect(
         queryClient.getQueryData<WorkspaceSessionSelection>(
           selectedSessionKey('abc', collab ? 'browser-tab' : 'shared')
@@ -415,7 +423,7 @@ for (const collab of [false, true]) {
         saving.resolve(Response.json({ sessionId: 'general' }))
         await opening
         expect(routed).toEqual([{ path: '/prefix/workspace/abc/overview', replace: true }])
-        expect(revealed).toEqual(['overview'])
+        expect(revealed).toEqual([true])
       })
 
       test('a refused conditional selection save does not open the chat', async () => {
@@ -469,7 +477,7 @@ for (const collab of [false, true]) {
         { sessionId: 'new', summary: 'New', lastModified: 2 }
       ])
       await navigate('moi:/chats/new')
-      expect(revealed).toEqual(['overview'])
+      expect(revealed).toEqual([true])
     })
   })
 }
diff --git a/client/features/workspace/useWorkspaceNavigation.ts b/client/features/workspace/useWorkspaceNavigation.ts
index 082783ab..21873f94 100644
--- a/client/features/workspace/useWorkspaceNavigation.ts
+++ b/client/features/workspace/useWorkspaceNavigation.ts
@@ -42,7 +42,7 @@ const rememberedAddresses = new Map<string, Map<WorkspaceTabId, string>>()
 
 type UseWorkspaceNavigationOptions = {
   views: ViewInfo[]
-  onOpenChat: (tab: WorkspaceTabId) => void
+  onOpenChat: () => void
 }
 
 export function useWorkspaceNavigation({ views, onOpenChat }: UseWorkspaceNavigationOptions) {
@@ -152,7 +152,7 @@ export function useWorkspaceNavigation({ views, onOpenChat }: UseWorkspaceNaviga
           checkCurrent()
         }
         go(addressPath(workspaceId, { tab, search: '' }), { replace: true })
-        onOpenChatRef.current(tab)
+        onOpenChatRef.current()
       } finally {
         if (chatRequest.current === controller) chatRequest.current = null
       }
@@ -163,12 +163,10 @@ export function useWorkspaceNavigation({ views, onOpenChat }: UseWorkspaceNaviga
 
   const navigateHref = useCallback(
     async (href: string, availableViews = views) => {
-      const target = resolveUrl(href, {
-        apiBase: `/api/workspaces/${encodeURIComponent(workspaceId)}`,
-        workspacePath: workspacePath(workspaceId)
-      })
       if (href.startsWith('moi:/files/') || !href.startsWith('moi:')) {
-        window.location.assign(target)
+        window.location.assign(
+          resolveUrl(href, { apiBase: `/api/workspaces/${encodeURIComponent(workspaceId)}` })
+        )
         return
       }
       const address = parseMoiHref(href)
@@ -178,7 +176,7 @@ export function useWorkspaceNavigation({ views, onOpenChat }: UseWorkspaceNaviga
       }
       if (!tabAvailable(address.tab, availableViews))
         throw new Error('This destination is unavailable in this workspace')
-      go(target)
+      go(addressPath(workspaceId, address))
     },
     [go, openLinkedChat, views, workspaceId]
   )
diff --git a/package.json b/package.json
index 364ce427..62c818a0 100644
--- a/package.json
+++ b/package.json
@@ -126,6 +126,7 @@
     "@types/react-resizable": "^3.0.8",
     "date-fns": "^4.4.0",
     "embla-carousel-react": "^8.6.0",
+    "linkedom": "0.18.12",
     "oxfmt": "^0.54.0",
     "oxlint": "^1.82.0",
     "react-day-picker": "^10.0.1",

From ea5809984e4ccc13a956c3ee1934b9f97801e020 Mon Sep 17 00:00:00 2001
From: Alexey Taktarov <molefrog@gmail.com>
Date: Fri, 9 Oct 2026 14:36:31 +0200
Subject: [PATCH 3/3] Minor refactor.

---
 .../use-workspace-navigation.dom.test.tsx     |  23 +++-
 .../workspace/useWorkspaceNavigation.test.tsx |   8 +-
 .../workspace/useWorkspaceNavigation.ts       | 114 +++++++++++-------
 docs/navigation.md                            |   3 +-
 4 files changed, 96 insertions(+), 52 deletions(-)

diff --git a/client/features/workspace/use-workspace-navigation.dom.test.tsx b/client/features/workspace/use-workspace-navigation.dom.test.tsx
index 2cce0c26..e09d818b 100644
--- a/client/features/workspace/use-workspace-navigation.dom.test.tsx
+++ b/client/features/workspace/use-workspace-navigation.dom.test.tsx
@@ -26,6 +26,7 @@ function mountNavigation(path: string, collab: boolean) {
   const location = new URL(`http://localhost/prefix/workspace/abc/${path}`)
   Object.defineProperty(window, 'location', { configurable: true, value: location })
   const storage = new Map<string, string>()
+  const entries: { kind: 'push' | 'replace'; href: string }[] = []
   const globals = {
     window,
     document,
@@ -36,8 +37,14 @@ function mountNavigation(path: string, collab: boolean) {
     addEventListener: window.addEventListener.bind(window),
     removeEventListener: window.removeEventListener.bind(window),
     history: {
-      pushState: (_state: unknown, _title: string, href: string) => move(href),
-      replaceState: (_state: unknown, _title: string, href: string) => move(href)
+      pushState: (_state: unknown, _title: string, href: string) => {
+        entries.push({ kind: 'push', href })
+        move(href)
+      },
+      replaceState: (_state: unknown, _title: string, href: string) => {
+        entries.push({ kind: 'replace', href })
+        move(href)
+      }
     },
     sessionStorage: {
       getItem: (key: string) => storage.get(key) ?? null,
@@ -181,7 +188,7 @@ function mountNavigation(path: string, collab: boolean) {
       )?.selected.scratchpad
     ).toBe('source')
   }
-  return { render, document, window, waitForNavigation }
+  return { render, document, window, waitForNavigation, history: entries }
 }
 
 for (const collab of [false, true]) {
@@ -190,6 +197,10 @@ for (const collab of [false, true]) {
       const fixture = mountNavigation('chats/source', collab)
       await fixture.render()
       await fixture.waitForNavigation()
+      // A direct load has no origin page, so the entry route is replaced in place.
+      expect(fixture.history).toEqual([
+        { kind: 'replace', href: '/prefix/workspace/abc/scratchpad' }
+      ])
     })
 
     test.each(['source', 'native'])(
@@ -204,6 +215,12 @@ for (const collab of [false, true]) {
         })
         expect(click.defaultPrevented).toBe(true)
         await fixture.waitForNavigation()
+        // One net history entry: the pushed chat route is replaced by its home
+        // tab, so Back returns to the page the link was clicked on.
+        expect(fixture.history).toEqual([
+          { kind: 'push', href: '/prefix/workspace/abc/chats/source' },
+          { kind: 'replace', href: '/prefix/workspace/abc/scratchpad' }
+        ])
       }
     )
   })
diff --git a/client/features/workspace/useWorkspaceNavigation.test.tsx b/client/features/workspace/useWorkspaceNavigation.test.tsx
index 14af239a..252c4491 100644
--- a/client/features/workspace/useWorkspaceNavigation.test.tsx
+++ b/client/features/workspace/useWorkspaceNavigation.test.tsx
@@ -342,7 +342,7 @@ for (const collab of [false, true]) {
       const { queryClient, selection, navigate, routed, revealed, writes, storage } = fixture
       queryClient.setQueryData(selectedSessionKey('abc'), { ...selection, pinned })
       await navigate(`moi:/chats/${id}`)
-      expect(routed).toEqual([{ path: `/prefix/workspace/abc/${tab}`, replace: true }])
+      expect(routed).toEqual([{ path: `/prefix/workspace/abc/${tab}`, replace: false }])
       expect(revealed).toEqual([true])
       expect(
         queryClient.getQueryData<WorkspaceSessionSelection>(selectedSessionKey('abc'))?.pinned
@@ -387,7 +387,7 @@ for (const collab of [false, true]) {
         { sessionId: 'legacy', summary: 'Legacy', lastModified: 1, tabId: 'agent' }
       ])
       await navigate('moi:/chats/legacy')
-      expect(routed).toEqual([{ path: '/prefix/workspace/abc/overview', replace: true }])
+      expect(routed).toEqual([{ path: '/prefix/workspace/abc/overview', replace: false }])
       expect(revealed).toEqual([true])
       expect(
         queryClient.getQueryData<WorkspaceSessionSelection>(
@@ -422,7 +422,7 @@ for (const collab of [false, true]) {
         expect(revealed).toEqual([])
         saving.resolve(Response.json({ sessionId: 'general' }))
         await opening
-        expect(routed).toEqual([{ path: '/prefix/workspace/abc/overview', replace: true }])
+        expect(routed).toEqual([{ path: '/prefix/workspace/abc/overview', replace: false }])
         expect(revealed).toEqual([true])
       })
 
@@ -442,7 +442,7 @@ for (const collab of [false, true]) {
         const original = { ...selection, pinned: 'pin' }
         queryClient.setQueryData(selectedSessionKey('abc'), original)
         await navigate(`moi:/chats/${id}`)
-        expect(routed).toEqual([{ path: '/prefix/workspace/abc/overview', replace: true }])
+        expect(routed).toEqual([{ path: '/prefix/workspace/abc/overview', replace: false }])
         expect(
           queryClient.getQueryData<WorkspaceSessionSelection>(selectedSessionKey('abc'))
         ).toEqual(original)
diff --git a/client/features/workspace/useWorkspaceNavigation.ts b/client/features/workspace/useWorkspaceNavigation.ts
index 21873f94..992ae31a 100644
--- a/client/features/workspace/useWorkspaceNavigation.ts
+++ b/client/features/workspace/useWorkspaceNavigation.ts
@@ -36,6 +36,13 @@ import {
 } from '@/lib/navigation'
 type NavigationOptions = { replace?: boolean }
 
+type OpenLinkedChatOptions = {
+  controller?: AbortController
+  // The chat route is an intermediate entry and gets replaced. Imperative
+  // requests push like view links, so Back returns to the origin page.
+  replace?: boolean
+}
+
 // A convenience for returning to tabs, never a second source of active state.
 // Memory-only, and scoped by workspace so switching workspaces cannot leak params.
 const rememberedAddresses = new Map<string, Map<WorkspaceTabId, string>>()
@@ -45,14 +52,56 @@ type UseWorkspaceNavigationOptions = {
   onOpenChat: () => void
 }
 
-export function useWorkspaceNavigation({ views, onOpenChat }: UseWorkspaceNavigationOptions) {
+type UseOpenChatLinkOptions = {
+  workspaceId: string
+  views: ViewInfo[]
+}
+
+// A chat link needs state prepared before its URL is valid: the chat becomes
+// the selection on its home tab, and a different pinned chat is unpinned
+// first. Resolves to that tab, or null when the chat or its tab is missing.
+// Navigation stays with the caller.
+export function useOpenChatLink({ workspaceId, views }: UseOpenChatLinkOptions) {
   const queryClient = useQueryClient()
-  const { layout, setLayout, workspaceId } = useWorkspaceLayoutCtx()
   const collabEnabled = useCollabEnabled()
   const [, , selectSessionForTab] = useSelectedSession()
   const { pinAsync } = usePinnedSession()
+  const open = useLatestRef(
+    async (sessionId: string, signal: AbortSignal): Promise<WorkspaceTabId | null> => {
+      const tab = await resolveChatLink(queryClient, workspaceId, sessionId, views, signal)
+      if (!tab) return null
+      // Direct loads can resolve the chat before selection and pin state load.
+      await queryClient.ensureQueryData(selectedSessionOptions(workspaceId))
+      if (collabEnabled)
+        await queryClient.ensureQueryData(selectedSessionOptions(workspaceId, 'browser-tab'))
+      signal.throwIfAborted()
+      const pinned = queryClient.getQueryData<WorkspaceSessionSelection>(
+        selectedSessionKey(workspaceId)
+      )?.pinned
+      if (pinned && pinned !== sessionId) {
+        await pinAsync(null)
+        signal.throwIfAborted()
+      }
+      if (pinned !== sessionId) {
+        await selectSessionForTab(sessionId, tab)
+        signal.throwIfAborted()
+      }
+      return tab
+    }
+  )
+  // Stable so a route effect does not restart a link when views or selection change.
+  return useCallback(
+    (sessionId: string, signal: AbortSignal) => open.current(sessionId, signal),
+    [open]
+  )
+}
+
+export function useWorkspaceNavigation({ views, onOpenChat }: UseWorkspaceNavigationOptions) {
+  const queryClient = useQueryClient()
+  const { layout, setLayout, workspaceId } = useWorkspaceLayoutCtx()
+  const collabEnabled = useCollabEnabled()
+  const openChat = useOpenChatLink({ workspaceId, views })
   const chatRequest = useRef<AbortController | null>(null)
-  const workspaceIdRef = useLatestRef(workspaceId)
   const onOpenChatRef = useLatestRef(onOpenChat)
   const [, navigate] = useLocation()
   const router = useRouter()
@@ -112,51 +161,28 @@ export function useWorkspaceNavigation({ views, onOpenChat }: UseWorkspaceNaviga
     [go, remembered, workspaceId]
   )
 
-  const openLinkedChat = useLatestRef(
-    async (sessionId: string, controller = new AbortController()) => {
+  // Navigation owns the link's lifetime: one request at a time, cancelled by
+  // any navigation or route change. The chat hook prepares state; this turns
+  // its answer into the home tab's URL and reveals the chat.
+  const openLinkedChat = useCallback(
+    async (
+      sessionId: string,
+      { controller = new AbortController(), replace = false }: OpenLinkedChatOptions = {}
+    ) => {
       chatRequest.current?.abort()
       chatRequest.current = controller
-      const originalUrl = window.location.href
-      const checkCurrent = () => {
-        if (window.location.href !== originalUrl || workspaceIdRef.current !== workspaceId)
-          controller.abort()
-        controller.signal.throwIfAborted()
-      }
       try {
-        const tab = await resolveChatLink(
-          queryClient,
-          workspaceId,
-          sessionId,
-          views,
-          controller.signal
-        )
-        checkCurrent()
-        if (!tab) {
-          go(addressPath(workspaceId, { tab: 'overview', search: '' }), { replace: true })
-          return
-        }
-        // Direct loads can resolve the chat before selection and pin state load.
-        await queryClient.ensureQueryData(selectedSessionOptions(workspaceId))
-        if (collabEnabled)
-          await queryClient.ensureQueryData(selectedSessionOptions(workspaceId, 'browser-tab'))
-        checkCurrent()
-        const pinned = queryClient.getQueryData<WorkspaceSessionSelection>(
-          selectedSessionKey(workspaceId)
-        )?.pinned
-        if (pinned && pinned !== sessionId) {
-          await pinAsync(null)
-          checkCurrent()
-        }
-        if (pinned !== sessionId) {
-          await selectSessionForTab(sessionId, tab)
-          checkCurrent()
-        }
-        go(addressPath(workspaceId, { tab, search: '' }), { replace: true })
-        onOpenChatRef.current()
+        const tab = await openChat(sessionId, controller.signal)
+        controller.signal.throwIfAborted()
+        // Finished before the redirect, which cancels whatever is still in flight.
+        chatRequest.current = null
+        go(addressPath(workspaceId, { tab: tab ?? 'overview', search: '' }), { replace })
+        if (tab) onOpenChatRef.current()
       } finally {
         if (chatRequest.current === controller) chatRequest.current = null
       }
-    }
+    },
+    [go, onOpenChatRef, openChat, workspaceId]
   )
 
   useEffect(() => () => chatRequest.current?.abort(), [path, search, workspaceId])
@@ -171,7 +197,7 @@ export function useWorkspaceNavigation({ views, onOpenChat }: UseWorkspaceNaviga
       }
       const address = parseMoiHref(href)
       if ('sessionId' in address) {
-        await openLinkedChat.current(address.sessionId)
+        await openLinkedChat(address.sessionId)
         return
       }
       if (!tabAvailable(address.tab, availableViews))
@@ -211,7 +237,7 @@ export function useWorkspaceNavigation({ views, onOpenChat }: UseWorkspaceNaviga
       return
     }
     const controller = new AbortController()
-    void openLinkedChat.current(linkedSessionId, controller).catch(error => {
+    void openLinkedChat(linkedSessionId, { controller, replace: true }).catch(error => {
       if (!controller.signal.aborted) reportError(error)
     })
     return () => controller.abort()
diff --git a/docs/navigation.md b/docs/navigation.md
index 603073f2..ec6cef2e 100644
--- a/docs/navigation.md
+++ b/docs/navigation.md
@@ -41,7 +41,8 @@ home tab, selects the chat, and reveals the sidebar or popup. Its browser addres
 `/workspace/<workspace-id>/chats/<session-id>`. Chats without tab
 attribution, including old Agent chats, open on Overview. Both pending and compiled
 views are valid destinations. The entry route is replaced with the tab's plain URL;
-it creates no separate chat tab and forwards no view parameters.
+it creates no separate chat tab and forwards no view parameters. Applet and CLI
+requests push the home tab like view links, so Back returns to the previous page.
 
 Opening a different chat unpins the workspace's current chat before selecting the
 requested one. Linking to the already pinned chat preserves its pin. Selection uses