fix(sidebar): open pinned Agent instead of All Agents - #20327

Keeps the pinned-Agent entry behaviour from #20327 and moves each rule into the
layer that owns it.

- `/app/agents` declares its search precedence in `search.middlewares` (a
  conflicting `sessionId` is dropped when the destination is an Agent entry), and
  `beforeLoad` goes back to resolving the entry plus the canonical
  session-only redirect.
- The shared `TabRouter` returns to its previous search handling. Omitted search
  already clears in the pinned `@tanstack/router-core`, so the previous object
  form and the PR's reducer form produce the same search: no route keeps a
  changed search semantic.
- The "opened from a pinned Agent" event travels as typed destination metadata
  into tab state instead of a `?agentId=` URL the page re-parses. `AgentPage`
  closes Manage Agents from one explicit predicate (`enteredByPin` or
  `activationResolved`) and consumes the marker; reusing a matching tab no
  longer replaces unrelated tab metadata.

Signed-off-by: cherry-coding[bot] <342372629+cherry-coding[bot]@users.noreply.github.com>

Restores the #20327 state so current main merges in without conflicts; the
refactor is re-applied immediately after the merge. Net PR diff is unchanged.

Signed-off-by: cherry-coding[bot] <342372629+cherry-coding[bot]@users.noreply.github.com>

Keeps the pinned-Agent entry behaviour from #20327 and moves each rule into the
layer that owns it.

- `/app/agents` declares its search precedence in `search.middlewares` (a
  conflicting `sessionId` is dropped when the destination is an Agent entry), and
  `beforeLoad` goes back to resolving the entry plus the canonical
  session-only redirect.
- The shared `TabRouter` returns to its previous search handling. Omitted search
  already clears in the pinned `@tanstack/router-core`, so the previous object
  form and the PR's reducer form produce the same search: no route keeps a
  changed search semantic.
- The "opened from a pinned Agent" event travels as typed destination metadata
  into tab state instead of a `?agentId=` URL the page re-parses. `AgentPage`
  closes Manage Agents from one explicit predicate (`enteredByPin` or
  `activationResolved`) and consumes the marker; reusing a matching tab no
  longer replaces unrelated tab metadata.

Signed-off-by: cherry-coding[bot] <342372629+cherry-coding[bot]@users.noreply.github.com>

)

### What this PR does

Before this PR: the pinned-Agent entry fix reached its goal through
three workarounds.

- The shared `TabRouter` navigated with a search **function** for every
route, replacing any search of any destination.
- "This tab was opened by clicking this pinned Agent" was carried as
`?agentId=` in the tab URL, and `AgentPage` re-parsed that URL by hand
(`split('?')` + `new URLSearchParams`) to decide whether to close Manage
Agents.
- Reusing a matching tab wrote `metadata: undefined`, wiping any other
tab metadata on it.

After this PR: identical behaviour, with each rule in the layer that
owns it.

1. `/app/agents` declares its search precedence in `search.middlewares`:
when the destination is an Agent entry (and is not a prepared
feedback/skill intent), the conflicting `sessionId` is dropped before
validation runs. `beforeLoad` is back to what it owns — entry resolution
(scoped resolver for an Agent entry, global resolver otherwise) and the
canonical `sessionId`-only redirect with `replace: true`.
2. `TabRouter` goes back to its previous search handling (`search:
search ? Object.fromEntries(new URLSearchParams(search)) : undefined`).
No route's search semantics change; the only route that declares
retention/precedence middleware is `/app/agents`. This is a semantic
revert: in the pinned `@tanstack/[email protected]`, `applyNext`
returns `{}` for an omitted search (`router.ts`, `applyNext`), so the
previous object form and the removed function form produce the same
search for every current route.
3. The pin event travels as typed destination metadata into tab state:
`agentSidebarShortcut.activate` emits `metadata: { agentPinPending: true
}`, `openWorkspace` merges it into the reused tab (even when the URL is
unchanged), and `AgentPage` closes Manage Agents from one explicit
predicate — `enteredByPin || activationResolved` — then consumes only
that field from a copied metadata bag. Reusing a matching tab no longer
replaces unrelated metadata.

Fixes #20251

### Why we need it and why it was done in this way

The behaviour is #20327's; this PR only moves each rule to the layer
that owns it, because the previous shape had two problems beyond style:
a change to a shared navigation component altered the search semantics
of every route (including `/app/chat?assistantId=`, `/app/code?tool=`,
`/app/knowledge?baseId=`, `/app/files?entryId=`), and the page
re-implemented `validateSearch` by parsing a URL string.

Tradeoffs made:
- The pin event is a boolean pending marker consumed synchronously by
the owning page — not a sticky "this session belongs to a pinned Agent"
flag (which would re-close Manage Agents after the user reopens it) and
not an activation token (no measurement showed an acknowledgement
clearing a later, still-unhandled activation).
- `beforeLoad` keeps resolution: the middleware can only express
precedence while a destination is built, so the asynchronous "which
session does this Agent resume" decision stays where the data lives.

Alternatives considered: `ToOptions.state` (not carried by the URL-only
tab bridge), `beforeLoad` context (cannot survive the normalising
redirect), and the built-in `retainSearchParams` / `stripSearchParams`
(they cannot express "drop this key only when another destination key is
present").

Links to places where the discussion took place: #20327, #20251.

### Breaking changes

None. Behaviour is intended to be identical to #20327; the visible fix
and the flag semantics are unchanged.

### Special notes for your reviewer

- **Relationship to #20327:** #20327 has landed on `main`, so this
branch has now merged `main` in: the PR diff is exactly the
normalisation (12 files), nothing else. Reviewing the top commit alone
is enough; the `Merge branch 'main'` and the preceding revert commit
exist only to re-base the normalisation without rewriting published
history, and their net effect is zero.
- **Test changes:** assertions that only recorded the previous
implementation were replaced with outcomes — `TabRouter.test.tsx` now
drives the real router instead of asserting a captured reducer call,
`runtime.test.ts` asserts active tab / tab count / metadata instead of
mock calls, `AgentPage.test.tsx` covers marker consumption (reopen and a
second activation) and keeps a raw tab-URL residue as a negative case
that must *not* close the directory, and
`agent-entry-normalization.test.tsx` mounts a real `RouterProvider` over
the production route options to check the dual-id case before load.

### Verification

```
pnpm exec vitest run --project renderer \
  src/renderer/components/app/sidebarShortcuts/__tests__/providers.test.tsx \
  src/renderer/components/app/sidebarShortcuts/__tests__/runtime.test.ts \
  src/renderer/components/layout/__tests__/TabRouter.test.tsx \
  src/renderer/pages/agents/__tests__/AgentPage.test.tsx \
  src/renderer/routes/app/__tests__/conversation-entry.test.ts \
  src/renderer/routes/app/__tests__/agent-entry-normalization.test.tsx \
  src/renderer/pages/agents/__tests__/routeSearch.test.ts \
  src/renderer/components/layout/__tests__/TabsProvider.test.tsx
# 8 files, 217 tests passed — re-run on the merged head (90bd399)

pnpm exec tsc --noEmit -p tsconfig.web.json --composite false   # exit 0
pnpm exec oxlint --deny-warnings <changed files>                # exit 0
pnpm exec oxfmt --check <changed files>                         # exit 0 (12 files)
```

Pre/post control (source reverted to the branch base, these tests kept):
15 failures across all six
suites, including the dual-id initial load, the leftover tab-URL residue
(must not close Manage Agents)
and the metadata transport cases — i.e. the new tests fail without the
normalisation and pass with it.

### Real-app evidence (Electron, built from this head)

The three frames below come from the real Electron app (`pnpm build` on
this head), driven through product
channels only: one Agent and one session are created via
`ai.agent.create` / `POST /agent-sessions`, the entry
is pinned through the `ui.sidebar_shortcut` preference, and everything
else is clicking the actual UI.
Flow: click the pinned Agent once → switch the centre pane to All Agents
(`Display mode` → `Manage Agents`)
→ click the same pinned sidebar entry again, i.e. the "latest session
already on screen" case.

**1. All Agents (Manage Agents) open, pinned Agent in the sidebar** —
this frame is byte-identical on the pre-fix build.

![All Agents open with the pinned Agent in the
sidebar](https://github.com/CherryHQ/cherry-studio/blob/test/21843-pr-evidence/docs/pr-evidence/21843/01-all-agents-open-with-pinned-rail-entry.png?raw=true)

**2. After clicking the pinned Agent: its session is shown and Manage
Agents is closed.**

![Clicking the pinned Agent opens its session and closes Manage
Agents](https://github.com/CherryHQ/cherry-studio/blob/test/21843-pr-evidence/docs/pr-evidence/21843/02-pinned-agent-opens-session-manage-agents-closed.png?raw=true)

**3. Control — the same step on the pre-fix build (`main` before
#20327): Manage Agents stays open, the reported bug.**

![Pre-fix control: Manage Agents stays
open](https://github.com/CherryHQ/cherry-studio/blob/test/21843-pr-evidence/docs/pr-evidence/21843/03-before-fix-manage-agents-stays-open.png?raw=true)

How it was run: an out-of-tree Playwright probe over the built app
(`_electron.launch`), one run per build with
a fresh `CS_DEV_PROFILE_ROOT`. On this head the assertion (`Manage
Agents` gone after the click) passes; on the
pre-fix build the same probe fails on exactly that assertion
(`toHaveCount(0)` received 1). Frames are captured
before the assertion, so #3 is the failing run's own screenshot.

### Not verified here

- No committed smoke spec for this flow: the probe lives outside the
repo, so CI still covers this path only at
the renderer/router level. Say the word if you want it promoted into
`tests/e2e/smoke/`.
- macOS only.

The `search` semantics claim above was measured, not assumed, with a
mounted router:

```
omitted search -> {}            search: true -> current search
object form == fresh-object reducer        explicit session kept
middleware runs for the initial memory-history URL before beforeLoad
```

### Release note

```release-note
NONE
```

---------

Signed-off-by: GokayAI <[email protected]>
Signed-off-by: cherry-coding[bot] <342372629+cherry-coding[bot]@users.noreply.github.com>
Co-authored-by: GokayAI <[email protected]>
Co-authored-by: cherry-coding[bot] <342372629+cherry-coding[bot]@users.noreply.github.com>